cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [error-handling] Silent error suppression in ADR inventory collection violates fail-fast specification #7282

New issue

Open

opened 2026-04-10 14:57:53 +00:00 by HAL9000 · 4 comments

HAL9000 commented

2026-04-10 14:57:53 +00:00

Owner

Background and Context

The _collect_adr_inventory function in hooks/adr_hooks.py silently suppresses two categories of errors that should be propagated according to the project's fail-fast specification. When ADR source files cannot be read or contain malformed YAML front-matter, the errors are swallowed with bare continue statements, causing affected files to be invisibly skipped from the documentation inventory.

This directly violates the project's established error handling principles: "Do not suppress errors — let exceptions propagate to top-level execution" and "No silent failures — raise exceptions, do not return null/defaults."

Current Behavior

File: hooks/adr_hooks.py
Function: _collect_adr_inventory
Lines: 382, 388

Two silent suppression sites exist:

OSError suppression (line 382): When Path(f.abs_src_path).read_text() fails due to permission issues, file not found, or I/O errors, the error is caught and silently ignored:

try:
    content = Path(f.abs_src_path).read_text(encoding="utf-8")
except OSError:
    continue  # Silent suppression violates fail-fast

YAML parsing error suppression (line 388): When yaml.safe_load() encounters malformed YAML front-matter, the error is caught and silently ignored:

try:
    meta = yaml.safe_load(fm_match.group(1)) or {}
except yaml.YAMLError:
    continue  # Silent suppression violates fail-fast

Expected Behavior

Per the project specification:

"Fail-fast principles: Validate all arguments in public/protected methods immediately"
"Exception propagation: Do not suppress errors — let them bubble up to top-level execution"
"No silent failures — raise exceptions, do not return null/defaults"

Errors should be surfaced to the user with sufficient context (file path, error details) to diagnose and fix the problem. File I/O errors and YAML parse errors should either fail the build or be logged as explicit warnings — never silently skipped.

Impact

Users may unknowingly have broken ADR files that silently disappear from generated documentation
Debugging documentation generation issues becomes extremely difficult without error visibility
Violates the project's established error handling principles, creating inconsistency with the rest of the codebase

Acceptance Criteria

_collect_adr_inventory no longer silently suppresses OSError exceptions
_collect_adr_inventory no longer silently suppresses yaml.YAMLError exceptions
Errors include the source file path and error details for user diagnosis
The fix is consistent with the project's fail-fast error handling policy
All nox stages pass
Coverage >= 97%

Metadata

Branch: bugfix/error-handling-silent-suppression-adr-inventory
Commit Message: fix(hooks): propagate OSError and YAMLError in ADR inventory collection instead of silently suppressing
Milestone: (none — backlog, see note below)
Parent Epic: (orphan — see note below)

Backlog note: This issue was discovered during autonomous operation
on milestone v3.5.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Subtasks

Identify the correct error handling strategy per project spec (propagate vs. log-and-continue)
Write a failing TDD test (@tdd_issue, @tdd_expected_fail) per the Bug Fix Workflow
Replace except OSError: continue at line 382 with proper error propagation or structured logging
Replace except yaml.YAMLError: continue at line 388 with proper error propagation or structured logging
Ensure error messages include the source file path and error details
Remove @tdd_expected_fail tag once fix is implemented
Update documentation if error handling behaviour is user-visible
Verify all nox stages pass

Definition of Done

Both silent suppression sites in _collect_adr_inventory are resolved
Errors include actionable context (file path, error type, details)
Fix is consistent with project fail-fast error handling policy
TDD regression test in place with @tdd_issue and @tdd_issue_<N> tags
@tdd_expected_fail tag removed from regression test
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: new-issue-creator

## Background and Context The `_collect_adr_inventory` function in `hooks/adr_hooks.py` silently suppresses two categories of errors that should be propagated according to the project's fail-fast specification. When ADR source files cannot be read or contain malformed YAML front-matter, the errors are swallowed with bare `continue` statements, causing affected files to be invisibly skipped from the documentation inventory. This directly violates the project's established error handling principles: *"Do not suppress errors — let exceptions propagate to top-level execution"* and *"No silent failures — raise exceptions, do not return null/defaults."* ## Current Behavior **File**: `hooks/adr_hooks.py` **Function**: `_collect_adr_inventory` **Lines**: 382, 388 Two silent suppression sites exist: 1. **OSError suppression (line 382)**: When `Path(f.abs_src_path).read_text()` fails due to permission issues, file not found, or I/O errors, the error is caught and silently ignored: ```python try: content = Path(f.abs_src_path).read_text(encoding="utf-8") except OSError: continue # Silent suppression violates fail-fast ``` 2. **YAML parsing error suppression (line 388)**: When `yaml.safe_load()` encounters malformed YAML front-matter, the error is caught and silently ignored: ```python try: meta = yaml.safe_load(fm_match.group(1)) or {} except yaml.YAMLError: continue # Silent suppression violates fail-fast ``` ## Expected Behavior Per the project specification: - *"Fail-fast principles: Validate all arguments in public/protected methods immediately"* - *"Exception propagation: Do not suppress errors — let them bubble up to top-level execution"* - *"No silent failures — raise exceptions, do not return null/defaults"* Errors should be surfaced to the user with sufficient context (file path, error details) to diagnose and fix the problem. File I/O errors and YAML parse errors should either fail the build or be logged as explicit warnings — never silently skipped. ## Impact - Users may unknowingly have broken ADR files that silently disappear from generated documentation - Debugging documentation generation issues becomes extremely difficult without error visibility - Violates the project's established error handling principles, creating inconsistency with the rest of the codebase ## Acceptance Criteria - `_collect_adr_inventory` no longer silently suppresses `OSError` exceptions - `_collect_adr_inventory` no longer silently suppresses `yaml.YAMLError` exceptions - Errors include the source file path and error details for user diagnosis - The fix is consistent with the project's fail-fast error handling policy - All nox stages pass - Coverage >= 97% ## Metadata - **Branch**: `bugfix/error-handling-silent-suppression-adr-inventory` - **Commit Message**: `fix(hooks): propagate OSError and YAMLError in ADR inventory collection instead of silently suppressing` - **Milestone**: *(none — backlog, see note below)* - **Parent Epic**: *(orphan — see note below)* > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.5.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Subtasks - [ ] Identify the correct error handling strategy per project spec (propagate vs. log-and-continue) - [ ] Write a failing TDD test (`@tdd_issue`, `@tdd_expected_fail`) per the Bug Fix Workflow - [ ] Replace `except OSError: continue` at line 382 with proper error propagation or structured logging - [ ] Replace `except yaml.YAMLError: continue` at line 388 with proper error propagation or structured logging - [ ] Ensure error messages include the source file path and error details - [ ] Remove `@tdd_expected_fail` tag once fix is implemented - [ ] Update documentation if error handling behaviour is user-visible - [ ] Verify all nox stages pass ## Definition of Done - [ ] Both silent suppression sites in `_collect_adr_inventory` are resolved - [ ] Errors include actionable context (file path, error type, details) - [ ] Fix is consistent with project fail-fast error handling policy - [ ] TDD regression test in place with `@tdd_issue` and `@tdd_issue_<N>` tags - [ ] `@tdd_expected_fail` tag removed from regression test - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: new-issue-creator

HAL9000 commented

2026-04-10 14:58:07 +00:00

Author

Owner

⚠️ Orphan Issue — Needs Manual Parent Epic Linking

This issue was created by the automated bug hunter and could not be automatically linked to a parent Epic. No existing open Epic was found that covers error handling in hooks/adr_hooks.py or ADR documentation infrastructure.

A maintainer should:

Identify or create an appropriate parent Epic for ADR/documentation infrastructure error handling
Link this issue as a child (this issue blocks the parent Epic) using Forgejo's dependency system

Until linked, this issue is an orphan which is not permitted per CONTRIBUTING.md.

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: new-issue-creator

⚠️ **Orphan Issue — Needs Manual Parent Epic Linking** This issue was created by the automated bug hunter and could not be automatically linked to a parent Epic. No existing open Epic was found that covers error handling in `hooks/adr_hooks.py` or ADR documentation infrastructure. A maintainer should: 1. Identify or create an appropriate parent Epic for ADR/documentation infrastructure error handling 2. Link this issue as a child (this issue **blocks** the parent Epic) using Forgejo's dependency system Until linked, this issue is an orphan which is not permitted per CONTRIBUTING.md. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: new-issue-creator

HAL9000 added the

labels

2026-04-10 15:02:56 +00:00

HAL9000 referenced this issue

2026-04-10 15:38:14 +00:00

BUG-HUNT: [type-safety] Unsafe type casting in tier configuration access bypasses static type checking #7300

HAL9000 referenced this issue

2026-04-10 15:45:35 +00:00

BUG-HUNT: [error-handling] Silent SyntaxError suppression in check-adr-compliance.py violates fail-fast principles #7303

HAL9000 referenced this issue

2026-04-10 15:47:09 +00:00

BUG-HUNT: [resource] Memory inefficient file operations in ADR inventory scanning lack proper resource management #7305

HAL9000 referenced this issue

2026-04-10 15:56:46 +00:00

BUG-HUNT: [resource] Memory inefficient file operations in ADR inventory scanning lack proper resource management #7305

HAL9000 added

and removed

labels

2026-04-14 06:24:22 +00:00

HAL9000 commented

2026-04-14 06:24:22 +00:00

Author

Owner

✅ Verified — Bug: silent error suppression in ADR inventory collection. MoSCoW: Should-have. Priority: Medium.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — Bug: silent error suppression in ADR inventory collection. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

2026-04-14 06:30:00 +00:00

Author

Owner

✅ Verified — Bug: silent error suppression in ADR inventory collection. MoSCoW: Should-have. Priority: Medium.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor