@poetic-ai/poetic 1.42.0

package/dist/chunk-EJGCZGUF.js

@@ -0,0 +1,1483 @@
+import {
+  sanitizeArgvForLogging,
+  sanitizeError,
+  sanitizeString
+} from "./chunk-LPITVM7M.js";
+import {
+  POETIC_COST_DEBUG,
+  POETIC_DEBUG,
+  POETIC_DEBUG_PATHS,
+  POETIC_DEBUG_SIGNALS,
+  POETIC_DEBUG_TELEMETRY,
+  POETIC_DEBUG_TEST_DETECTION,
+  POETIC_DEBUG_TIMEOUT,
+  POETIC_JSON_OUTPUT,
+  POETIC_OUTPUT_JSON,
+  POETIC_QUIET,
+  POETIC_WARNINGS_CONSOLE_LEVEL,
+  readEnv
+} from "./chunk-5DLKYTQX.js";
+
+// src/core/debug.ts
+function isDebugMode() {
+  return readEnv(POETIC_DEBUG).value ?? false;
+}
+function isTelemetryDebug() {
+  return readEnv(POETIC_DEBUG_TELEMETRY).value ?? false;
+}
+function isPathDebug() {
+  return readEnv(POETIC_DEBUG_PATHS).value ?? false;
+}
+function isTimeoutDebug() {
+  return (readEnv(POETIC_DEBUG_TIMEOUT).value ?? false) || isDebugMode();
+}
+function isSignalDebug() {
+  return readEnv(POETIC_DEBUG_SIGNALS).value ?? false;
+}
+function isTestDetectionDebug() {
+  return readEnv(POETIC_DEBUG_TEST_DETECTION).value ?? false;
+}
+function isCostDebug() {
+  return readEnv(POETIC_COST_DEBUG).value || isDebugMode();
+}
+function isVerboseOrDebug(verbose) {
+  return verbose === true || isDebugMode();
+}
+function sanitizeDebugArg(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (typeof value === "string") {
+    return sanitizeString(value);
+  }
+  if (value instanceof Error) {
+    return sanitizeError(value);
+  }
+  if (Array.isArray(value)) {
+    if (value.every((item) => typeof item === "string")) {
+      return sanitizeArgvForLogging(value);
+    }
+    return value.map((item) => sanitizeDebugArg(item, seen));
+  }
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  if (seen.has(value)) {
+    return "[Circular]";
+  }
+  seen.add(value);
+  const sanitized = {};
+  for (const [key, item] of Object.entries(value)) {
+    sanitized[sanitizeString(key)] = sanitizeDebugArg(item, seen);
+  }
+  seen.delete(value);
+  return sanitized;
+}
+function debugLog(message, ...args) {
+  if (isDebugMode()) {
+    const sanitizedMessage = sanitizeString(message);
+    if (args.length > 0) {
+      console.error(`[DEBUG] ${sanitizedMessage}`, ...args.map((arg) => sanitizeDebugArg(arg)));
+    } else {
+      console.error(`[DEBUG] ${sanitizedMessage}`);
+    }
+  }
+}
+function telemetryDebugLog(message, ...args) {
+  if (isTelemetryDebug()) {
+    const sanitizedMessage = sanitizeString(message);
+    if (args.length > 0) {
+      console.error(
+        `[TELEMETRY-DEBUG] ${sanitizedMessage}`,
+        ...args.map((arg) => sanitizeDebugArg(arg))
+      );
+    } else {
+      console.error(`[TELEMETRY-DEBUG] ${sanitizedMessage}`);
+    }
+  }
+}
+
+// src/core/warnings/emit.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// src/core/warnings/registry.ts
+var WARNING_REGISTRY = {
+  // ========================================================================
+  // WORKSPACE EDITS (WS-xxx)
+  // ========================================================================
+  "WS-001": {
+    code: "WS-001",
+    severity: "INFO" /* INFO */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace edit emitted but not applied (provider lacks edit support)",
+    commonCauses: [
+      "Provider in analysis-only mode",
+      "Provider does not support workspace edits",
+      "Dry-run mode enabled"
+    ],
+    recoveryMechanism: "Edits captured in telemetry for manual review",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: 'Check provider capabilities: workspaceEditSupport should be "patch-protocol"'
+  },
+  "WS-002": {
+    code: "WS-002",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace warning umbrella code (legacy - use WS-002A/WS-002B/WS-002D/WS-002E/WS-002F/WS-002G)",
+    commonCauses: ["Permission denied", "File locked by another process", "Disk full"],
+    recoveryMechanism: "Retry with temporary file + atomic rename",
+    expectedRecoveryRate: 95,
+    actionRequired: false,
+    diagnosticProcedure: "Check file permissions and disk space"
+  },
+  "WS-002A": {
+    code: "WS-002A",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace file write failed, retrying with backup strategy",
+    commonCauses: ["Permission denied", "File locked by another process", "Disk full"],
+    recoveryMechanism: "Retry with temporary file + atomic rename",
+    expectedRecoveryRate: 95,
+    actionRequired: false,
+    diagnosticProcedure: "Check file permissions and disk space"
+  },
+  "WS-002B": {
+    code: "WS-002B",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace edits recovered from stdout fallback channel",
+    commonCauses: [
+      "Provider emitted brace-encoded edits in stdout instead of file channel",
+      "Partial protocol mismatch in workspace edit output"
+    ],
+    recoveryMechanism: "Parsed fallback stdout edits and continued execution",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect provider output channel and prefer file-based edits.jsonl protocol"
+  },
+  "WS-002D": {
+    code: "WS-002D",
+    severity: "WARN" /* WARN */,
+    category: "performance" /* PERFORMANCE */,
+    description: "Task tracking state conflict or missing task context",
+    commonCauses: [
+      "Duplicate task start/update calls",
+      "Concurrent updates referencing unknown task IDs",
+      "Out-of-order telemetry event delivery"
+    ],
+    recoveryMechanism: "Operation skipped while tracker remains available",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Review task lifecycle ordering and telemetry event sequencing"
+  },
+  "WS-002E": {
+    code: "WS-002E",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Worktree/provider setup filesystem operation failed (non-fatal)",
+    commonCauses: [
+      "Unable to create provider config directory",
+      "Failed to copy provider snapshot/config files",
+      "Filesystem permission or transient IO contention"
+    ],
+    recoveryMechanism: "Continue execution with degraded setup",
+    expectedRecoveryRate: 80,
+    actionRequired: false,
+    diagnosticProcedure: "Check setup metadata paths and verify filesystem permissions"
+  },
+  "WS-002F": {
+    code: "WS-002F",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Feature flag storage temp-file cleanup failed",
+    commonCauses: ["Temp file locked", "Permission denied", "Concurrent cleanup race"],
+    recoveryMechanism: "Best-effort cleanup deferred to next run",
+    expectedRecoveryRate: 90,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect feature flag temp paths and concurrent writers"
+  },
+  "WS-002G": {
+    code: "WS-002G",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Planning metadata parse/load warning for tech debt item",
+    commonCauses: ["Malformed markdown frontmatter", "Unexpected planning metadata schema"],
+    recoveryMechanism: "Skipped unreadable item and continued listing",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Validate planning markdown metadata schema for the reported file"
+  },
+  "WS-003": {
+    code: "WS-003",
+    severity: "ERROR" /* ERROR */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Edit operation failed after all retry attempts",
+    commonCauses: ["Persistent permission issues", "Invalid file path", "Filesystem error"],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: true,
+    diagnosticProcedure: "Review variant execution logs and filesystem state"
+  },
+  "WS-004": {
+    code: "WS-004",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace edits emitted but not all were applied (legacy code, use WS-004A/WS-004B)",
+    commonCauses: [
+      "Unsafe file paths (absolute paths, parent traversal)",
+      "Excluded files (node_modules, .git, etc.)",
+      "Invalid edit operations",
+      "File permission issues"
+    ],
+    recoveryMechanism: "Applied valid edits, rejected unsafe ones",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check telemetry for workspace_edits_emitted vs workspace_edits_applied delta"
+  },
+  "WS-004A": {
+    code: "WS-004A",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Stale workspace edit file detected and ignored",
+    commonCauses: [
+      "Edit file from previous run still present",
+      "Worktree cloned with stale edits.jsonl tracked in git",
+      "Race condition between runs"
+    ],
+    recoveryMechanism: "Stale file deleted, no edits from this source applied",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check if .poetic/edits.jsonl is tracked in git (should be gitignored)"
+  },
+  "WS-004B": {
+    code: "WS-004B",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Some workspace edits were rejected during validation",
+    commonCauses: [
+      "Unsafe file paths (absolute paths, parent traversal)",
+      "Excluded files (node_modules, .git, etc.)",
+      "Invalid edit operations",
+      "File permission issues"
+    ],
+    recoveryMechanism: "Applied valid edits, rejected unsafe ones",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check telemetry metadata for editsEmitted, editsApplied, and editsRejected counts"
+  },
+  "WS-004C": {
+    code: "WS-004C",
+    severity: "ERROR" /* ERROR */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Provider failed to emit workspace edits despite FILE: targets and code intent",
+    commonCauses: [
+      "Provider parsed FILE: spec but emitted zero workspace edits",
+      "Protocol mismatch: provider emits prose-wrapped or diff-format output instead of clean JSONL",
+      "Provider treats task as analysis despite code intent",
+      "Missing .poetic/edits.jsonl file or empty git diff"
+    ],
+    recoveryMechanism: "None - provider failed to emit any workspace edits for FILE: targets",
+    expectedRecoveryRate: 0,
+    actionRequired: true,
+    diagnosticProcedure: 'Check workspaceEditsRequested (should be > 0), filesChanged (should be > 0), and executionIntent (should be "code"); verify .poetic/edits.jsonl exists; review provider output format'
+  },
+  "WS-004E": {
+    code: "WS-004E",
+    severity: "INFO" /* INFO */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace edit matched FILE target using fuzzy path matching",
+    commonCauses: [
+      "User specified FILE: greet.ts but provider output src/utils/greet.ts",
+      "User specified FILE: ./src/foo.ts but provider output src/foo.ts",
+      "Path normalization differences between user input and provider output"
+    ],
+    recoveryMechanism: "Fuzzy match accepted; edit applied successfully",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Review fuzzy match details in metadata (targetPath, editPath, matchType)"
+  },
+  "WS-004F": {
+    code: "WS-004F",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "No git-detected changes matched FILE targets",
+    commonCauses: [
+      "Provider ignored FILE targets and made no relevant edits",
+      "Task was answered as analysis/planning despite code intent",
+      "Worktree changes were reverted or never written",
+      "FILE targets did not match repository paths"
+    ],
+    recoveryMechanism: "None - no on-target changes detected for FILE targets",
+    expectedRecoveryRate: 0,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect metadata (fileTargets, gitChanges, attemptedEdits) and provider output; verify FILE targets are correct and the task intent is code"
+  },
+  "WS-006": {
+    code: "WS-006",
+    severity: "ERROR" /* ERROR */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Files in git status do not exist on disk",
+    commonCauses: [
+      "Worktree corruption or cleanup race condition",
+      "Git index out of sync with filesystem",
+      "File deletion between status check and validation",
+      "Filesystem mount issue"
+    ],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: true,
+    diagnosticProcedure: "Check worktree integrity with git fsck; verify filesystem mount status; review cleanup timing"
+  },
+  "WS-007": {
+    code: "WS-007",
+    severity: "ERROR" /* ERROR */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace write rejected due to empty or missing file contents",
+    commonCauses: [
+      "Provider emitted an empty writeFile payload",
+      "Provider omitted the contents field for a writeFile edit",
+      "Provider produced a stub declaration without a corresponding fill write",
+      "Tool/protocol failure truncated the write payload before application"
+    ],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: true,
+    diagnosticProcedure: "Inspect workspace edit payloads for empty or missing contents; verify the provider emitted full file content; review `.poetic/edits.jsonl` or provider tool output"
+  },
+  "WS-008": {
+    code: "WS-008",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Preflight: FILE: targets reference non-existent files",
+    commonCauses: [
+      "FILE: specification references files that do not exist",
+      "Typo in file path",
+      "Task describes modifying a file that should be created",
+      "Function/file was renamed or moved"
+    ],
+    recoveryMechanism: "Add (create) annotation to paths for new files, or correct path to existing file",
+    expectedRecoveryRate: 80,
+    actionRequired: false,
+    diagnosticProcedure: "Verify FILE: paths exist; use (create) annotation for new files; check for typos"
+  },
+  "WS-009": {
+    code: "WS-009",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "FILE: target was created instead of modified (fabrication detected)",
+    commonCauses: [
+      "Provider created a new file instead of modifying existing code",
+      "Task specified modifying a function/file that does not exist",
+      "Provider misunderstood the task and fabricated a solution",
+      "FILE: path typo causing creation of new file with similar name"
+    ],
+    recoveryMechanism: "Verify FILE: targets exist before execution; use correct function/file names",
+    expectedRecoveryRate: 50,
+    actionRequired: true,
+    diagnosticProcedure: "Check git status for ?? (untracked) files; verify task intent was modification not creation"
+  },
+  "WS-010": {
+    code: "WS-010",
+    severity: "ERROR" /* ERROR */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace write rejected due to placeholder file contents",
+    commonCauses: [
+      'Provider emitted placeholder text like "(modified content)" instead of real file contents',
+      'Provider returned a sentinel such as "[FULL_FILE_CONTENT_*]" or "<FILE_CONTENT>"',
+      "Provider failed mid-edit and produced a stub response"
+    ],
+    recoveryMechanism: 'Retry provider with strict "full file contents only" requirement; verify edits.jsonl',
+    expectedRecoveryRate: 70,
+    actionRequired: true,
+    diagnosticProcedure: "Inspect .poetic/edits.jsonl for placeholder payloads; verify the target file was not truncated; re-run with stricter prompt/tooling"
+  },
+  "WS-011": {
+    code: "WS-011",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace write rejected due to suspiciously short stub content",
+    commonCauses: [
+      'Provider produced an incomplete stub like "// TODO" for an existing file',
+      "Provider attempted to write a minimal placeholder export/module stub",
+      "Provider truncation or tool failure returned partial output"
+    ],
+    recoveryMechanism: "Retry provider; require full file content and forbid placeholders/stubs",
+    expectedRecoveryRate: 60,
+    actionRequired: false,
+    diagnosticProcedure: "Check whether the file should be small/new; inspect provider output for truncation; verify git diff for unintended file wipes"
+  },
+  "WS-012": {
+    code: "WS-012",
+    severity: "ERROR" /* ERROR */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "FILE: targets specified but files do not exist on disk",
+    commonCauses: [
+      "Provider failed to create target files",
+      "Path mismatch between FILE: spec and provider output",
+      "File write failed silently",
+      "Provider ignored FILE: specification"
+    ],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: true,
+    diagnosticProcedure: "Check provider logs for file creation; verify FILE: paths are relative; review provider FILE: specification support"
+  },
+  "WS-201": {
+    code: "WS-201",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Off-target edits were corrected or flagged during FILE target enforcement",
+    commonCauses: [
+      "Provider attempted edits outside requested FILE targets",
+      "FILE target path mismatch or normalization differences",
+      "Git-detected changes leaked outside target scope during execution"
+    ],
+    recoveryMechanism: "Off-target edits dropped, reverted, or flagged based on enforcement policy",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect correctionStage, action, enforcementPath, and affected file metadata against requested FILE targets"
+  },
+  "WS-202": {
+    code: "WS-202",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Provider reported file changes but git evidence was empty",
+    commonCauses: [
+      "Provider reported file modifications that never landed on disk",
+      "Worktree or git status changed between provider execution and validation",
+      "Provider/native runner overstated modified file evidence"
+    ],
+    recoveryMechanism: "Execution continued with degraded confidence in provider file-change signal",
+    expectedRecoveryRate: 0,
+    actionRequired: false,
+    diagnosticProcedure: "Compare provider-reported files with git status, commit movement, and FILE target matches"
+  },
+  "WS-203": {
+    code: "WS-203",
+    severity: "INFO" /* INFO */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Workspace edits were applied but produced no git diff",
+    commonCauses: [
+      "Edits were no-ops (writing identical content)",
+      "Edits normalized formatting to the existing file state",
+      "Workspace edits landed in paths excluded from git change evidence"
+    ],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: false,
+    diagnosticProcedure: "Compare workspace_edits_applied to git diff evidence and provider-reported modified files"
+  },
+  // ========================================================================
+  // EXECUTION BOUNDARY (EB-xxx)
+  // ========================================================================
+  "EB-001": {
+    code: "EB-001",
+    description: "Execution boundary triggered (idle, ceiling, or progress stagnation)",
+    severity: "WARN" /* WARN */,
+    category: "performance" /* PERFORMANCE */,
+    commonCauses: [
+      "Agent idle beyond configured threshold (no stdout/CPU activity)",
+      "Hard ceiling reached for workload class",
+      "Progress stagnation: no meaningful change across consecutive checks"
+    ],
+    recoveryMechanism: "Execution terminated; results up to boundary are preserved",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check trigger field in metadata (idle/ceiling/progress); review elapsedMs vs effectiveCeilingMs; inspect source for the boundary owner"
+  },
+  // ========================================================================
+  // GIT VALIDATION (GIT-xxx)
+  // ========================================================================
+  "GIT-001": {
+    code: "GIT-001",
+    severity: "ERROR" /* ERROR */,
+    category: "validation" /* VALIDATION */,
+    description: "Success reported but git shows zero tracked file changes",
+    commonCauses: [
+      "Provider emitted empty workspace edits",
+      "Provider wrote only files under gitignored paths",
+      "Analysis-only output when code was expected",
+      "Provider bug or misconfiguration",
+      "Git worktree sync issue"
+    ],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: true,
+    diagnosticProcedure: "Check workspaceEditsApplied vs filesChanged; inspect ignoredPaths metadata; verify executionIntent (should not be analysis); review provider logs"
+  },
+  // ========================================================================
+  // PROVIDER EXECUTION (PR-xxx)
+  // ========================================================================
+  "PR-001": {
+    code: "PR-001",
+    severity: "ERROR" /* ERROR */,
+    category: "provider_execution" /* PROVIDER_EXECUTION */,
+    description: "Provider execution failed with non-zero exit code",
+    commonCauses: ["Provider internal error", "API timeout", "Invalid configuration"],
+    recoveryMechanism: "Fallback to alternative provider if configured",
+    expectedRecoveryRate: 30,
+    actionRequired: true,
+    diagnosticProcedure: "Check provider logs and API status"
+  },
+  "PR-002": {
+    code: "PR-002",
+    severity: "WARN" /* WARN */,
+    category: "provider_execution" /* PROVIDER_EXECUTION */,
+    description: "Provider execution timed out, using partial results",
+    commonCauses: ["Network latency", "Large task complexity", "Provider overload"],
+    recoveryMechanism: "Return partial results, mark as incomplete",
+    expectedRecoveryRate: 70,
+    actionRequired: false,
+    diagnosticProcedure: "Review task complexity and provider latency metrics"
+  },
+  "PR-003": {
+    code: "PR-003",
+    severity: "INFO" /* INFO */,
+    category: "provider_execution" /* PROVIDER_EXECUTION */,
+    description: "Provider API rate limit approaching",
+    commonCauses: ["High request volume", "Aggressive retry policy"],
+    recoveryMechanism: "Throttle requests and backoff",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Review rate limit configuration and request patterns"
+  },
+  "PR-004": {
+    code: "PR-004",
+    severity: "WARN" /* WARN */,
+    category: "provider_execution" /* PROVIDER_EXECUTION */,
+    description: "Provider API rate limit exceeded",
+    commonCauses: ["Provider hard quota reached", "Burst traffic above allowed rate"],
+    recoveryMechanism: "Honor retry-after hints and reduce concurrency",
+    expectedRecoveryRate: 90,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect provider 429 responses and adjust concurrency/backoff"
+  },
+  "PR-007": {
+    code: "PR-007",
+    severity: "INFO" /* INFO */,
+    category: "provider_execution" /* PROVIDER_EXECUTION */,
+    description: "Provider capability mismatch: requested feature not supported or fell back",
+    commonCauses: [
+      "Reasoning effort requested but provider CLI does not support it",
+      "Requested effort level fell back to a lower tier or was ignored",
+      "Provider version predates the capability"
+    ],
+    recoveryMechanism: "Execution continues without the requested capability",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check requestedReasoningEffort vs effectiveReasoningEffort in metadata; upgrade provider CLI or omit the effort flag"
+  },
+  "PR-006": {
+    code: "PR-006",
+    severity: "INFO" /* INFO */,
+    category: "provider_execution" /* PROVIDER_EXECUTION */,
+    description: "Provider output format drift detected (metadata gap, missing signal, or parse fallback)",
+    commonCauses: [
+      "CLI output schema changed between provider versions",
+      "Token usage fields renamed or removed in JSONL stream",
+      "Completion signal JSON absent from provider stdout",
+      "JSONL parse failed and raw stdout fallback was used"
+    ],
+    recoveryMechanism: "Execution continues with degraded metadata; check provider CLI version",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect metadata.field and metadata.detail for the affected output field; update the parser if the CLI format has changed"
+  },
+  "PR-005": {
+    code: "PR-005",
+    severity: "WARN" /* WARN */,
+    category: "provider_execution" /* PROVIDER_EXECUTION */,
+    description: "Competitive variant terminated due to zero file progress within threshold",
+    commonCauses: [
+      "Provider analyzing code without writing changes (stuck in planning phase)",
+      "Provider encountered internal error without surfacing exit code",
+      "Task complexity too high for the configured timeout budget"
+    ],
+    recoveryMechanism: "Variant aborted early; competition continues with remaining variants",
+    expectedRecoveryRate: 80,
+    actionRequired: false,
+    diagnosticProcedure: "Increase POETIC_ZERO_PROGRESS_KILL_MS or review provider logs for stuck analysis loops"
+  },
+  // ========================================================================
+  // PROMPT MODE (PM-xxx)
+  // ========================================================================
+  "PM-001": {
+    code: "PM-001",
+    severity: "WARN" /* WARN */,
+    category: "provider_execution" /* PROVIDER_EXECUTION */,
+    description: "Requested workspace mode did not match the mode applied by the execution path",
+    commonCauses: [
+      "Provider native runner did not receive workspaceMode option",
+      "Provider prompt adapter disabled via *_LOCAL_VERTICAL_SLICE=0",
+      "Workspace mode not supported by provider/runner (fallback to passthrough)"
+    ],
+    recoveryMechanism: "Run continues with applied mode; mismatch is recorded for audit",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect workspaceModeRequested vs workspaceMode in variant result; ensure provider adapter is enabled and workspaceMode is propagated to runner"
+  },
+  // ========================================================================
+  // AUTHENTICATION (AUTH-xxx)
+  // ========================================================================
+  "AUTH-001": {
+    code: "AUTH-001",
+    severity: "ERROR" /* ERROR */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "AI judge authentication failed at execution time",
+    commonCauses: ["Claude CLI not authenticated", "Claude CLI not installed"],
+    recoveryMechanism: "Run `claude` and complete /login (or set CLAUDE_CODE_OAUTH_TOKEN via `claude setup-token`)",
+    expectedRecoveryRate: 100,
+    actionRequired: true,
+    diagnosticProcedure: "Authenticate Claude CLI: run `claude` and complete /login"
+  },
+  // ========================================================================
+  // VALIDATION (VAL-xxx)
+  // ========================================================================
+  "VAL-001": {
+    code: "VAL-001",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "AI judge evaluation unavailable or failed (legacy - use specific VAL-001X codes)",
+    commonCauses: [
+      "Breaking changes introduced",
+      "Flaky tests",
+      "Invalid test configuration",
+      "Judge credentials not configured",
+      "Judge execution error"
+    ],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: true,
+    diagnosticProcedure: "Review test failures and variant changes; check AUTH-001 for credential issues"
+  },
+  "VAL-001A": {
+    code: "VAL-001A",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "AI judge evaluation timed out",
+    commonCauses: [
+      "Judge execution exceeded timeout",
+      "Network latency to AI provider",
+      "Large number of variants to evaluate"
+    ],
+    recoveryMechanism: "Fall back to algorithmic selection",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check network connectivity; consider increasing timeout or reducing variant count"
+  },
+  "VAL-001B": {
+    code: "VAL-001B",
+    severity: "ERROR" /* ERROR */,
+    category: "validation" /* VALIDATION */,
+    description: "AI judge evaluation runtime error",
+    commonCauses: [
+      "Judge execution threw exception",
+      "Invalid response from AI provider",
+      "Configuration error",
+      "Unexpected input format"
+    ],
+    recoveryMechanism: "Fall back to algorithmic selection",
+    expectedRecoveryRate: 100,
+    actionRequired: true,
+    diagnosticProcedure: "Check judge logs for exception details; verify AI provider configuration"
+  },
+  "VAL-001C": {
+    code: "VAL-001C",
+    severity: "INFO" /* INFO */,
+    category: "validation" /* VALIDATION */,
+    description: "No variants to evaluate",
+    commonCauses: [
+      "All variants filtered out",
+      "No variants provided to judge",
+      "Empty competition"
+    ],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: false,
+    diagnosticProcedure: "Verify variant execution completed successfully; check filtering criteria"
+  },
+  "VAL-001D": {
+    code: "VAL-001D",
+    severity: "ERROR" /* ERROR */,
+    category: "validation" /* VALIDATION */,
+    description: "Judge result parsing failure",
+    commonCauses: [
+      "Malformed JSON in judge response",
+      "Unexpected response structure",
+      "Missing required fields",
+      "Type mismatch in parsed data"
+    ],
+    recoveryMechanism: "Fall back to algorithmic selection",
+    expectedRecoveryRate: 90,
+    actionRequired: true,
+    diagnosticProcedure: "Check judge response format; verify AI provider output matches expected schema"
+  },
+  "VAL-001E": {
+    code: "VAL-001E",
+    severity: "INFO" /* INFO */,
+    category: "validation" /* VALIDATION */,
+    description: "Judge telemetry logging failed (non-critical)",
+    commonCauses: [
+      "Database write failed",
+      "Telemetry system unavailable",
+      "Invalid telemetry data format"
+    ],
+    recoveryMechanism: "Judge evaluation continues without telemetry",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check database connectivity; verify telemetry configuration"
+  },
+  "VAL-001F": {
+    code: "VAL-001F",
+    severity: "INFO" /* INFO */,
+    category: "validation" /* VALIDATION */,
+    description: "Bandit state save failed (non-critical)",
+    commonCauses: ["Database write failed", "State file inaccessible", "Invalid state format"],
+    recoveryMechanism: "Evaluation continues; learning state not persisted",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check database connectivity and filesystem permissions; verify state serialization"
+  },
+  "VAL-001G": {
+    code: "VAL-001G",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Judge evaluation approaching timeout budget",
+    commonCauses: [
+      "Large diff or prompt payload",
+      "High variant count",
+      "Provider latency variance",
+      "Insufficient timeout budget for current workload"
+    ],
+    recoveryMechanism: "Evaluation may still complete; increase budget/deadline if warnings persist",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect utilization metadata and recent judge durations; tune budget scaling or timeout settings"
+  },
+  "VAL-002": {
+    code: "VAL-002",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Linting errors detected but not blocking",
+    commonCauses: ["Code style violations", "Type errors", "Unused imports"],
+    recoveryMechanism: "Auto-fix with linter if configured",
+    expectedRecoveryRate: 80,
+    actionRequired: false,
+    diagnosticProcedure: "Run linter with --fix flag"
+  },
+  "VAL-003": {
+    code: "VAL-003",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Build succeeded with warnings",
+    commonCauses: ["Deprecated API usage", "Type mismatches", "Unused variables"],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: false,
+    diagnosticProcedure: "Review build output for warnings"
+  },
+  "VAL-004": {
+    code: "VAL-004",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Variant key exclusion during canonical map construction",
+    commonCauses: [
+      "Variant key contained invalid or empty segments",
+      "Duplicate canonical key after normalization"
+    ],
+    recoveryMechanism: "Normalized variants proceed with the canonical key; excluded variants are dropped from judge evaluation",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check compete output for normalization preview; verify variant --variant flags match provider model resolution"
+  },
+  "CTX-001": {
+    code: "CTX-001",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Analysis context injection failed for dependency-aware subtask",
+    commonCauses: [
+      "Missing dependency artifacts",
+      "Artifact read or parse error",
+      "Subtask dependency metadata mismatch"
+    ],
+    recoveryMechanism: "Subtask executes without injected dependency context (degraded but non-blocking)",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check dependency artifact files under .poetic/artifacts and verify subtask dependency IDs"
+  },
+  "SEM-000": {
+    code: "SEM-000",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Semantic validation enabled but no provider configured; skipping",
+    commonCauses: [
+      "Semantic checks enabled without setting semanticCheck.provider",
+      "Provider config not loaded or missing for selected provider"
+    ],
+    recoveryMechanism: "Proceed without semantic validation (graceful degradation)",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Configure semanticCheck.provider (and credentials) or disable --autoloop-semantic-check"
+  },
+  "SEM-001": {
+    code: "SEM-001",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Semantic progress evaluation failed; skipping semantic validation",
+    commonCauses: [
+      "Provider execution error (auth, timeout, rate limit)",
+      "Provider output could not be parsed",
+      "Semantic evaluator runtime error"
+    ],
+    recoveryMechanism: "Proceed without semantic validation (graceful degradation)",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check provider auth and logs; retry with a different provider or disable --autoloop-semantic-check"
+  },
+  "SEM-002": {
+    code: "SEM-002",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Semantic acceptance criteria evaluation failed; skipping semantic validation",
+    commonCauses: [
+      "Provider execution error (auth, timeout, rate limit)",
+      "Provider output could not be parsed",
+      "Acceptance criteria prompt returned malformed JSON"
+    ],
+    recoveryMechanism: "Proceed without semantic validation (graceful degradation)",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check provider auth and logs; retry or disable --autoloop-semantic-check"
+  },
+  "VE-001": {
+    code: "VE-001",
+    severity: "INFO" /* INFO */,
+    category: "validation" /* VALIDATION */,
+    description: "Opportunistic verification evidence observed during execution",
+    commonCauses: ["Test, typecheck, lint, or diff signal was already produced by a run"],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Use telemetry metadata for offline analysis; this signal must not gate execution"
+  },
+  // ========================================================================
+  // PERFORMANCE (PERF-xxx)
+  // ========================================================================
+  "PERF-001": {
+    code: "PERF-001",
+    severity: "WARN" /* WARN */,
+    category: "performance" /* PERFORMANCE */,
+    description: "Variant execution exceeded time budget",
+    commonCauses: ["Task complexity", "Provider latency", "Resource constraints"],
+    recoveryMechanism: "Continue execution, flag for review",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Review execution timeline and provider metrics"
+  },
+  "PERF-002": {
+    code: "PERF-002",
+    severity: "INFO" /* INFO */,
+    category: "performance" /* PERFORMANCE */,
+    description: "Memory usage approaching threshold",
+    commonCauses: ["Large file processing", "Memory leak", "Excessive caching"],
+    recoveryMechanism: "Trigger garbage collection",
+    expectedRecoveryRate: 90,
+    actionRequired: false,
+    diagnosticProcedure: "Profile memory usage and check for leaks"
+  },
+  "PERF-003": {
+    code: "PERF-003",
+    severity: "INFO" /* INFO */,
+    category: "performance" /* PERFORMANCE */,
+    description: "Repair loop skipped to avoid expensive no-op retries",
+    commonCauses: [
+      "FILE: targets were missing, and the provider asked for clarification (no edits)",
+      "Task references a symbol/file that does not exist"
+    ],
+    recoveryMechanism: "Fix FILE: targets (or mark with (create)) and re-run; otherwise answer the clarification question and retry",
+    expectedRecoveryRate: 95,
+    actionRequired: false,
+    diagnosticProcedure: "Check WS-008/WS-009 warnings and provider output; verify referenced symbols/files exist before repairing"
+  },
+  "PERF-004": {
+    code: "PERF-004",
+    severity: "WARN" /* WARN */,
+    category: "performance" /* PERFORMANCE */,
+    description: "Process timeout escalation triggered by ProcessLimiter",
+    commonCauses: [
+      "Provider or child process exceeded its allotted runtime",
+      "Delegated execution stalled before producing a final response",
+      "Subprocess ignored graceful termination and required escalation"
+    ],
+    recoveryMechanism: "ProcessLimiter sends terminateDelegate/SIGTERM/SIGKILL and untracks orphans",
+    expectedRecoveryRate: 95,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect timeoutMs, processDescription, and stage metadata; compare provider runtime against configured limits"
+  },
+  // ========================================================================
+  // CONFIGURATION (CFG-xxx)
+  // ========================================================================
+  "CFG-001": {
+    code: "CFG-001",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Configuration issue; using fallback behavior",
+    commonCauses: [
+      "Rejected or missing environment value",
+      "Invalid key or path format",
+      "Optional config not set"
+    ],
+    recoveryMechanism: "Fallback to alternative provider or default path",
+    expectedRecoveryRate: 80,
+    actionRequired: true,
+    diagnosticProcedure: "Check environment variables and provider configuration"
+  },
+  "CFG-002": {
+    code: "CFG-002",
+    severity: "INFO" /* INFO */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Using default configuration value",
+    commonCauses: ["Configuration not specified", "Config file not found"],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Review configuration documentation"
+  },
+  "CFG-003": {
+    code: "CFG-003",
+    severity: "ERROR" /* ERROR */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Invalid configuration value, cannot proceed",
+    commonCauses: ["Type mismatch", "Value out of range", "Invalid format"],
+    recoveryMechanism: void 0,
+    expectedRecoveryRate: 0,
+    actionRequired: true,
+    diagnosticProcedure: "Validate configuration against schema"
+  },
+  "CFG-004": {
+    code: "CFG-004",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Using packaged provider catalog defaults",
+    commonCauses: ["No project provider policy override", "Project provider policy unavailable"],
+    recoveryMechanism: "Load the digest-checked provider catalog shipped with the CLI",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Run 'poetic provider list' to inspect the effective catalog"
+  },
+  "CFG-005": {
+    code: "CFG-005",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: 'Ambiguous 3-part variant interpreted as provider:model:strategy. Prefer 4-part "provider:model:strategy:mode" or 2-part "provider:strategy" to be explicit.',
+    commonCauses: [
+      "User specified provider:X:strategy where X is not a registered strategy name",
+      "Variant could be interpreted as provider:strategy:mode with a different second token"
+    ],
+    recoveryMechanism: "Use 4-part form (provider:model:strategy:mode) or 2-part form (provider:strategy) to eliminate ambiguity",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Rewrite as provider:model:strategy:mode (e.g. claude:sonnet:conservative:local) or as provider:strategy (e.g. claude:conservative). Run 'poetic explain strategies' for available strategies."
+  },
+  "CFG-006": {
+    code: "CFG-006",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Cleanup threshold matches all worktrees",
+    commonCauses: ["Cleanup command was run with --max-age 0", "Cleanup TTL was set to zero"],
+    recoveryMechanism: "Cleanup still applies age floor and dirty/uninspectable safety gates",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Use cleanup dry-run output to verify candidates before running with --execute."
+  },
+  "CFG-007": {
+    code: "CFG-007",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Provider model override differs from registry default",
+    commonCauses: [
+      "Project or user config intentionally pins a provider model",
+      "Provider registry default changed after the config file was written"
+    ],
+    recoveryMechanism: "Configured override remains in effect",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Review provider model overrides and remove them when registry defaults should apply"
+  },
+  "CFG-008": {
+    code: "CFG-008",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Provider not found in registry; falling back to default",
+    commonCauses: [
+      "Configured provider name is misspelled or unknown",
+      "Provider was removed from the registry"
+    ],
+    recoveryMechanism: "Resolution returns 'auto' so execution can continue",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Run poetic config validate to confirm the provider name; check providers.yaml for the canonical list."
+  },
+  "CFG-009": {
+    code: "CFG-009",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Legacy JavaScript config file ignored",
+    commonCauses: ["Project or user config still uses poetic.config.js or poetic.config.mjs"],
+    recoveryMechanism: "JSONC config remains canonical; legacy JavaScript config is not loaded",
+    expectedRecoveryRate: 100,
+    actionRequired: true,
+    diagnosticProcedure: "Move settings into poetic.config.jsonc, then remove the legacy JavaScript config file."
+  },
+  "CFG-010": {
+    code: "CFG-010",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "POETIC_ROOT and POETIC_REPO point at different local roots; POETIC_ROOT wins",
+    commonCauses: [
+      "Shell profile or wrapper exports both root override variables",
+      "A lane worktree run inherited POETIC_ROOT from another checkout",
+      "Operator intended POETIC_REPO targeting but POETIC_ROOT is still set"
+    ],
+    recoveryMechanism: "Repo-root resolution continues with POETIC_ROOT precedence",
+    expectedRecoveryRate: 100,
+    actionRequired: true,
+    diagnosticProcedure: "Unset one override or make both variables point at the same checkout before running write commands."
+  },
+  "CFG-011": {
+    code: "CFG-011",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "User config could not be read; configured model aliases were skipped",
+    commonCauses: [
+      "poetic.config.jsonc has a syntax error",
+      "A provider block contains a key the config schema does not allow",
+      "The config file is present but unreadable"
+    ],
+    recoveryMechanism: "Model resolution continues using registry and project defaults",
+    expectedRecoveryRate: 100,
+    actionRequired: true,
+    diagnosticProcedure: "Run 'poetic config validate' to see the parse or schema error, fix the file, then re-run."
+  },
+  "CFG-LEGACY": {
+    code: "CFG-LEGACY",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Deprecated config file found and ignored",
+    commonCauses: [
+      "A legacy defaults.yaml or poetic.json file is still present",
+      "POETIC_DEFAULTS_PATH points at an old config file"
+    ],
+    recoveryMechanism: "Canonical poetic.config.jsonc files remain in effect",
+    expectedRecoveryRate: 100,
+    actionRequired: true,
+    diagnosticProcedure: "Move settings into the appropriate poetic.config.jsonc file, then remove the deprecated config file."
+  },
+  "CFG-LOAD-ERR": {
+    code: "CFG-LOAD-ERR",
+    severity: "ERROR" /* ERROR */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Configuration loading failed",
+    commonCauses: ["Unreadable configuration file", "Unexpected configuration loader error"],
+    recoveryMechanism: "Fallback to default configuration when no explicit invalid config is present",
+    expectedRecoveryRate: 80,
+    actionRequired: true,
+    diagnosticProcedure: "Inspect the reported configuration path and loader error, then run poetic config validate"
+  },
+  // FILE: warning disabled per A/B test results (2026-02-02)
+  // Changed from WARN to INFO - FILE: specification is no longer enforced.
+  // To re-enable: change severity back to WarningSeverity.WARN
+  "CUR-001": {
+    code: "CUR-001",
+    severity: "INFO" /* INFO */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Cursor variant without FILE: specification (informational)",
+    commonCauses: ["Cursor used without FILE/FILES markers in prompt"],
+    // 2026-02-02: FILE: specification no longer required per A/B test results.
+    // Previously advisory; now purely informational.
+    recoveryMechanism: "FILE: specification is optional - no action required",
+    expectedRecoveryRate: 100,
+    // No enforcement, always recovers
+    actionRequired: false,
+    diagnosticProcedure: "FILE: specification is optional. Add FILE/FILES entries only if disambiguation is needed."
+  },
+  "JDG-001": {
+    code: "JDG-001",
+    severity: "INFO" /* INFO */,
+    category: "validation" /* VALIDATION */,
+    description: "Judge evaluation completed, no winner declared (expected outcome)",
+    commonCauses: [
+      "All variants scored below confidence threshold",
+      "Margin between top variants too narrow",
+      "Intentional baseline fallback"
+    ],
+    recoveryMechanism: "Review variant scores; this is often expected behavior for close competitions",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check variant scores in telemetry; verify threshold and margin settings"
+  },
+  "JDG-010": {
+    code: "JDG-010",
+    severity: "INFO" /* INFO */,
+    category: "validation" /* VALIDATION */,
+    description: "Judge CLI not available (skipping AI-powered evaluation)",
+    commonCauses: [
+      "Claude CLI not installed",
+      "Claude CLI not accessible in PATH",
+      "CLI version check timed out"
+    ],
+    recoveryMechanism: "Install Claude CLI: npm install -g @anthropic-ai/claude-code. Winner selection falls back to algorithmic heuristic.",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Run `claude --version` to verify CLI installation and accessibility"
+  },
+  "JDG-011": {
+    code: "JDG-011",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "Judge provider CLI installed but a recent authentication failure is cached",
+    commonCauses: [
+      "Provider CLI logged in previously but the session/token expired",
+      "Provider credentials were revoked or rotated",
+      "A prior provider call failed authentication and was cached by auth-liveness"
+    ],
+    recoveryMechanism: "Re-authenticate the judge provider CLI (see the provider auth note), then retry; judge selection otherwise falls back to algorithmic heuristics.",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Run `poetic doctor --probe --refresh` after re-authenticating to clear the cached auth failure."
+  },
+  "TEL-001": {
+    code: "TEL-001",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Judge telemetry or state persistence failed (non-blocking)",
+    commonCauses: ["Database write failed", "State file inaccessible", "Event emission error"],
+    recoveryMechanism: "Judge evaluation continues; telemetry data may be incomplete",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Check database connectivity and filesystem permissions; review telemetry logs"
+  },
+  "JDG-002": {
+    code: "JDG-002",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "AI judge CLI unavailable or unhealthy",
+    commonCauses: [
+      "Claude CLI installed but failing (auth, rate limits, network)",
+      "Claude CLI on PATH but cannot execute headless",
+      "Stale or corrupted Claude CLI installation"
+    ],
+    recoveryMechanism: "Fallback to alternative judge providers (Gemini, OpenAI)",
+    expectedRecoveryRate: 100,
+    actionRequired: true,
+    diagnosticProcedure: "Run `claude --version` to verify availability and check stderr for the failing command"
+  },
+  "JDG-003": {
+    code: "JDG-003",
+    severity: "WARN" /* WARN */,
+    category: "configuration" /* CONFIGURATION */,
+    description: "multi-agent judge is experimental: it does not yet evaluate as reliably as the ai and multi-lens judges, costs more to run, and depends on Claude/Task/sandbox availability; it runs only when explicitly selected and is ordered last for fallback promotion",
+    commonCauses: [
+      "multi-agent included in --judge-run / --ai-judge-run",
+      "--judge-primary or --ai-judge-primary set to multi-agent",
+      "--judge multi-agent selected"
+    ],
+    recoveryMechanism: "No action required; rely on the ai and multi-lens judges for dependable winner selection",
+    expectedRecoveryRate: 100,
+    actionRequired: false,
+    diagnosticProcedure: "Remove multi-agent from the judge run set or primary selection to silence this notice"
+  },
+  "JUDGE-001": {
+    code: "JUDGE-001",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Multi-Lens judge scoring collapse detected",
+    commonCauses: [
+      "All non-winner variants receiving identical or near-identical scores",
+      "Insufficient score variance to meaningfully rank variants",
+      "Multi-Lens LLM arbitration returning undifferentiated scores",
+      "Core Lens dominating with identical metrics across variants"
+    ],
+    recoveryMechanism: "Diagnostic data logged for analysis; consider retrying with different temperature or comparing against AI/Multi-Agent judges",
+    expectedRecoveryRate: 70,
+    actionRequired: false,
+    diagnosticProcedure: "Check scoringCollapseDetection in metadata; review coefficient of variation and unique score counts; inspect Multi-Lens LLM output for differentiation"
+  },
+  // ========================================================================
+  // FLYWHEEL MERGE (FM-xxx)
+  // ========================================================================
+  "FM-001": {
+    code: "FM-001",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Flywheel merge task-status sync skipped or incomplete",
+    commonCauses: [
+      "One or more task status transitions failed (e.g. ENOENT, invalid status)",
+      "Task file missing or moved since workflow execution",
+      "Sprint ID mismatch between manifest and task file"
+    ],
+    recoveryMechanism: "Merge succeeded; task status updates can be applied manually via poetic task update",
+    expectedRecoveryRate: 80,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect taskSyncFailures in merge result; check tasksFailed and failedTaskIds metadata; verify task files exist in the sprint directory"
+  },
+  "FM-002": {
+    code: "FM-002",
+    severity: "WARN" /* WARN */,
+    category: "validation" /* VALIDATION */,
+    description: "Sprint workflow result is missing task transition artifacts",
+    commonCauses: [
+      "Lifecycle callback drain did not persist transitions",
+      "Workflow result was written before any stage result existed",
+      "Older workflow result format without top-level taskTransitions"
+    ],
+    recoveryMechanism: "Merge succeeded; task status updates can be applied manually via poetic task update",
+    expectedRecoveryRate: 80,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect the workflow result JSON for taskTransitions; check sprint-bridge callback logs and task status history"
+  },
+  // ========================================================================
+  // PLANNING WRITEBACK (WB-xxx)
+  // ========================================================================
+  "WB-001": {
+    code: "WB-001",
+    severity: "WARN" /* WARN */,
+    category: "workspace_edits" /* WORKSPACE_EDITS */,
+    description: "Planning writeback retry exhausted and entry was moved to dead-letter queue",
+    commonCauses: [
+      "Target work item file was deleted or moved",
+      "File permissions prevent appending activity",
+      "Persistent filesystem error during writeback retry"
+    ],
+    recoveryMechanism: "Dead-letter entry preserves the activity for manual replay or inspection",
+    expectedRecoveryRate: 70,
+    actionRequired: false,
+    diagnosticProcedure: "Inspect .poetic/writeback-dead-letter.jsonl and verify the target itemPath exists and is writable"
+  }
+};
+function getWarningDefinition(code) {
+  return WARNING_REGISTRY[code];
+}
+
+// src/core/warnings/warning-factory.ts
+var WarningFactory = class _WarningFactory {
+  /**
+   * Create a structured warning from a warning code.
+   *
+   * Retrieves warning definition from registry and merges with runtime context
+   * and options. Returns immutable frozen warning object.
+   *
+   * @param code - Warning code (e.g., 'WS-001', 'PR-042')
+   * @param context - Execution context at time of warning
+   * @param options - Optional overrides for severity, category, metadata, etc.
+   * @returns Immutable structured warning
+   *
+   * @example
+   * const warning = WarningFactory.create('WS-001', {
+   *   taskId: 'abc123',
+   *   subsystem: 'workspace-edits'
+   * });
+   */
+  static create(code, context, options = {}) {
+    const definition = getWarningDefinition(code);
+    if (!definition) {
+      return _WarningFactory.createUnknownWarning(code, context, options);
+    }
+    const warning = {
+      code,
+      severity: options.severity ?? definition.severity,
+      category: options.category ?? definition.category,
+      message: definition.description,
+      timestamp: Date.now(),
+      context: {
+        subsystem: context.subsystem ?? "unknown",
+        taskId: context.taskId,
+        provider: context.provider,
+        strategy: context.strategy,
+        variant: context.variant,
+        executionPhase: context.executionPhase
+      },
+      metadata: options.metadata,
+      recovered: options.recovered,
+      recoveryMechanism: options.recoveryMechanism ?? definition.recoveryMechanism
+    };
+    return Object.freeze(warning);
+  }
+  /**
+   * Create warning for unknown code (fallback).
+   *
+   * Used when warning code is not found in registry. Creates a generic
+   * warning with minimal metadata to ensure emission never fails.
+   *
+   * @param code - Unknown warning code
+   * @param context - Execution context
+   * @param options - Optional overrides
+   * @returns Immutable structured warning
+   *
+   * @internal
+   */
+  static createUnknownWarning(code, context, options) {
+    return Object.freeze({
+      code,
+      severity: options.severity ?? "WARN" /* WARN */,
+      category: options.category ?? "configuration" /* CONFIGURATION */,
+      message: `Unknown warning code: ${code}`,
+      timestamp: Date.now(),
+      context: {
+        subsystem: context.subsystem ?? "unknown",
+        taskId: context.taskId,
+        provider: context.provider,
+        strategy: context.strategy,
+        variant: context.variant,
+        executionPhase: context.executionPhase
+      },
+      metadata: options.metadata,
+      recovered: options.recovered,
+      recoveryMechanism: options.recoveryMechanism
+    });
+  }
+  /**
+   * Create custom warning (for ad-hoc warnings not in registry).
+   *
+   * Use this for one-off warnings that don't warrant a registry entry.
+   * For recurring warnings, add to registry instead.
+   *
+   * @param severity - Warning severity level
+   * @param category - Warning category
+   * @param message - Human-readable warning message
+   * @param context - Execution context
+   * @param options - Optional metadata and recovery info
+   * @returns Immutable structured warning
+   *
+   * @example
+   * const warning = WarningFactory.createCustom(
+   *   WarningSeverity.WARN,
+   *   WarningCategory.VALIDATION,
+   *   'Custom validation failed: field X is invalid',
+   *   { subsystem: 'validator', taskId: 'abc123' }
+   * );
+   */
+  static createCustom(severity, category, message, context, options = {}) {
+    return Object.freeze({
+      code: "CUSTOM",
+      severity,
+      category,
+      message,
+      timestamp: Date.now(),
+      context: {
+        subsystem: context.subsystem ?? "unknown",
+        taskId: context.taskId,
+        provider: context.provider,
+        strategy: context.strategy,
+        variant: context.variant,
+        executionPhase: context.executionPhase
+      },
+      metadata: options.metadata,
+      recovered: options.recovered,
+      recoveryMechanism: options.recoveryMechanism
+    });
+  }
+};
+
+// src/core/warnings/emit.ts
+function getWarningConsoleLevel() {
+  return readEnv(POETIC_WARNINGS_CONSOLE_LEVEL).value;
+}
+function isWarningConsoleQuietRequested() {
+  return readEnv(POETIC_QUIET).value === true;
+}
+function isWarningConsoleJsonRequested() {
+  return readEnv(POETIC_OUTPUT_JSON).value === true || readEnv(POETIC_JSON_OUTPUT).value === true;
+}
+function shouldLogWarningToConsole(severity) {
+  if (process.env.POETIC_WARNINGS_CONSOLE === "false") return false;
+  if ((isWarningConsoleQuietRequested() || isWarningConsoleJsonRequested()) && severity !== "ERROR") {
+    return false;
+  }
+  const level = getWarningConsoleLevel();
+  if (level === "silent") return false;
+  if (severity === "ERROR") return true;
+  if (level === "error") return false;
+  if (severity === "WARN") return true;
+  if (level === "warn") return false;
+  return true;
+}
+function shouldIncludeWarningMetadata() {
+  if (isDebugMode()) return true;
+  if (process.env.POETIC_WARNINGS_CONSOLE_METADATA === "1") return true;
+  return getWarningConsoleLevel() === "info";
+}
+var globalCollector = null;
+var collectorScopeStorage = new AsyncLocalStorage();
+function setGlobalWarningCollector(collector) {
+  const scope = collectorScopeStorage.getStore();
+  if (scope) {
+    scope.collector = collector;
+    return;
+  }
+  globalCollector = collector;
+}
+function runWithWarningCollectorScope(fn, options = {}) {
+  return collectorScopeStorage.run(
+    {
+      collector: null,
+      suppressNonErrorConsole: options.suppressNonErrorConsole ?? false
+    },
+    fn
+  );
+}
+function getGlobalWarningCollector() {
+  const scope = collectorScopeStorage.getStore();
+  if (scope) {
+    return scope.collector;
+  }
+  return globalCollector;
+}
+function isConsoleSuppressedByScope(warning) {
+  return warning.severity !== "ERROR" && collectorScopeStorage.getStore()?.suppressNonErrorConsole === true;
+}
+function emitWarning(code, context, options = {}) {
+  const warning = WarningFactory.create(code, context, options);
+  const activeCollector = getGlobalWarningCollector();
+  if (activeCollector) {
+    activeCollector.add(warning);
+  }
+  if (!options.skipConsole && !isConsoleSuppressedByScope(warning) && shouldLogWarningToConsole(warning.severity)) {
+    const level = warning.severity === "ERROR" ? "error" : "warn";
+    const metadataSuffix = shouldIncludeWarningMetadata() && warning.metadata && Object.keys(warning.metadata).length > 0 ? ` metadata: ${JSON.stringify(warning.metadata)}` : "";
+    const compactSuffix = metadataSuffix.length === 0 && warning.code === "WS-003" && warning.metadata && typeof warning.metadata === "object" && typeof warning.metadata.worktreeName === "string" ? ` (${warning.metadata.worktreeName})` : "";
+    console[level](`[${warning.code}] ${warning.message}${metadataSuffix}${compactSuffix}`);
+  }
+  return warning;
+}
+function emitCustomWarning(severity, category, message, context, options = {}) {
+  const warning = WarningFactory.createCustom(severity, category, message, context, options);
+  const activeCollector = getGlobalWarningCollector();
+  if (activeCollector) {
+    activeCollector.add(warning);
+  }
+  if (!options.skipConsole && !isConsoleSuppressedByScope(warning) && shouldLogWarningToConsole(warning.severity)) {
+    const level = warning.severity === "ERROR" ? "error" : "warn";
+    const metadataSuffix = shouldIncludeWarningMetadata() && warning.metadata && Object.keys(warning.metadata).length > 0 ? ` metadata: ${JSON.stringify(warning.metadata)}` : "";
+    console[level](`[${warning.code}] ${warning.message}${metadataSuffix}`);
+  }
+  return warning;
+}
+
+export {
+  isDebugMode,
+  isTelemetryDebug,
+  isPathDebug,
+  isTimeoutDebug,
+  isSignalDebug,
+  isTestDetectionDebug,
+  isCostDebug,
+  isVerboseOrDebug,
+  debugLog,
+  telemetryDebugLog,
+  WARNING_REGISTRY,
+  WarningFactory,
+  setGlobalWarningCollector,
+  runWithWarningCollectorScope,
+  emitWarning,
+  emitCustomWarning
+};
+//# sourceMappingURL=chunk-EJGCZGUF.js.map