[spec] Refactor Safety Audit Finding Types and Harden Forgejo CLI Helper #39

New issue

Closed

opened 2026-08-30 16:14:08 +03:00 by jalmari · 0 comments

jalmari commented

2026-08-30 16:14:08 +03:00

Owner

Problem Statement

The codebase review showed two maintainability issues:

The classification engine safety audit interface uses plain strings instead of typed domain structures. This causes primitive obsession across the safety audit boundary.
The Forgejo CLI helper script contains duplicate environment parsing code. It also uses an implicit fallback organization name during dependency payload creation.

Solution

Add a typed domain enum (AuditFindingType) in the classification domain module to show safety audit finding categories.
Update the classification engine and the safety auditor to use AuditFindingType.
Improve the Forgejo CLI helper script to require explicit repository paths and use standard environment loading.

User Stories

As a domain developer, I want safety audit methods to return typed finding categories, so that tools catch typo errors.
As a maintainer, I want the safety auditor to use structured finding types, so that domain rules remain clear and type-safe.
As a developer who uses the Forgejo script, I want the script to validate repository names on startup, so that API calls do not fail with bad endpoints.
As an automated agent, I want environment loading in the Forgejo script to follow repository standards, so that credentials parse identically across all tools.
As a test author, I want all safety audit assertions to check AuditFindingType enum values, so that test contracts stay strict and readable.

Implementation Decisions

Add AuditFindingType as a string enum (str, Enum) in the classification domain module.
Change ClassificationEngine.audit_safety to return tuples of (AuditFindingType, AnalysisResult).
Update SafetyAuditor to inspect AuditFindingType constants.
Validate owner/repo format during ForgejoClient initialization.
Consolidate environment parsing routines in the Forgejo script.

Testing Decisions

Unit tests check ClassificationEngine.audit_safety and SafetyAuditor.audit with AuditFindingType values.
Tool tests check ForgejoClient repository validation for valid and invalid repository names.
All tests must pass with zero failures and zero regressions.

Out of Scope

Changing heuristic keyword lists or safety tier definitions.
Changing IMAP gateway protocol handling.
Adding third-party external dependencies.

Further Notes

Follows ASD-STE100 language rules and repository single-context architecture.

## Problem Statement The codebase review showed two maintainability issues: 1. The classification engine safety audit interface uses plain strings instead of typed domain structures. This causes primitive obsession across the safety audit boundary. 2. The Forgejo CLI helper script contains duplicate environment parsing code. It also uses an implicit fallback organization name during dependency payload creation. ## Solution 1. Add a typed domain enum (`AuditFindingType`) in the classification domain module to show safety audit finding categories. 2. Update the classification engine and the safety auditor to use `AuditFindingType`. 3. Improve the Forgejo CLI helper script to require explicit repository paths and use standard environment loading. ## User Stories 1. As a domain developer, I want safety audit methods to return typed finding categories, so that tools catch typo errors. 2. As a maintainer, I want the safety auditor to use structured finding types, so that domain rules remain clear and type-safe. 3. As a developer who uses the Forgejo script, I want the script to validate repository names on startup, so that API calls do not fail with bad endpoints. 4. As an automated agent, I want environment loading in the Forgejo script to follow repository standards, so that credentials parse identically across all tools. 5. As a test author, I want all safety audit assertions to check `AuditFindingType` enum values, so that test contracts stay strict and readable. ## Implementation Decisions - Add `AuditFindingType` as a string enum (`str, Enum`) in the classification domain module. - Change `ClassificationEngine.audit_safety` to return tuples of `(AuditFindingType, AnalysisResult)`. - Update `SafetyAuditor` to inspect `AuditFindingType` constants. - Validate `owner/repo` format during `ForgejoClient` initialization. - Consolidate environment parsing routines in the Forgejo script. ## Testing Decisions - Unit tests check `ClassificationEngine.audit_safety` and `SafetyAuditor.audit` with `AuditFindingType` values. - Tool tests check `ForgejoClient` repository validation for valid and invalid repository names. - All tests must pass with zero failures and zero regressions. ## Out of Scope - Changing heuristic keyword lists or safety tier definitions. - Changing IMAP gateway protocol handling. - Adding third-party external dependencies. ## Further Notes Follows ASD-STE100 language rules and repository single-context architecture.

jalmari added the

ready-for-agent

spec

labels

2026-08-30 16:14:08 +03:00

jalmari referenced this issue

2026-08-30 16:14:08 +03:00

[refactor] Introduce Typed Safety Audit Finding Types in Classification Engine #40

jalmari referenced this issue

2026-08-30 16:14:08 +03:00

[refactor] Harden Forgejo CLI Helper Repository Parsing and Environment Loading #41

jalmari referenced this issue