audit(legibility): re-run readiness scorecard; ratify "ready for evaluation" #416

New Issue

marcel · 2026-05-04T16:18:18+02:00

marcel commented

2026-05-04 16:18:18 +02:00

Context

Part of Epic #411 — Cleanup. This is CLEANUP-5: the final gate. Re-run the legibility audit AFTER all of Epics 2–4 and CLEANUP-1..4 are done, and produce the final readiness scorecard. If 🟢🟢, the codebase is ready to send to Anja and Tobias.

Per the Legibility Rubric, this re-validates ALL of C1–C10.

Inputs

The original audit reports under docs/audits/audit-*-report.md (Epic 1 outputs)
The original docs/LEGIBILITY-READINESS.md (AUDIT-6 / #393 output)
The completion state of every other Codebase Legibility milestone issue

Method

Re-walk the per-subsystem orient template (TEMPLATE-ORIENT-001 — see #387 first comment) against EACH subsystem. Don't shortcut — the whole point is verification.
For each rubric check, mark current status (PASS / FAIL).
Compare to the original audit results. Flag any check that:
- WAS passing, now failing (regression — investigate before closing)
- WAS failing, now passing (confirmed cleanup worked)
- WAS failing, still failing (decide: do we accept it, or open a follow-up?)
Update docs/audits/audit-{frontend,backend,ocr,db,rest}-report.md IN PLACE with new scorecards (don't create new files; preserve the diff in git history)
Refresh docs/LEGIBILITY-READINESS.md with new §1 executive summary, §2 per-subsystem table, §3 aggregate scorecard, §4 remaining top-10, §5 refactor verdict (now historical), §6 evaluation verdict (the one that matters), §7 open questions.

§6 evaluation verdict criteria

🟢 Ready to send to Anja and Tobias — zero Critical findings, ≥80% of Major findings resolved or accepted
🟡 Ready after these specific tasks — list them; if they're truly small, do them in this PR
🔴 Not ready — list specific blockers; this kicks off another loop

Acceptance criteria

Every audit report under docs/audits/ has been re-scored
docs/LEGIBILITY-READINESS.md reflects current state, not Epic 1 state
§6 verdict is justified by reference to specific rubric findings
If §6 is 🔴, this issue does NOT close and a follow-up cycle is opened
If §6 is 🟢, the closing comment of this issue includes a one-paragraph "ready" announcement that you (Marcel) can copy into a message to Anja and Tobias
PR opened and merged

Dependency

Hard blocked by: every other issue in the Codebase Legibility milestone (#7).

Specifically: Epic 1 (#387), Epic 2 (#394), Epic 3 (#402), Epic 4 (#406), and CLEANUP-1..4 (the four sibling issues in Epic 5).

Definition of Done

PR merged; this issue closes; the Codebase Legibility milestone closes; Anja and Tobias are sent the announcement.

Dispatch

Best done by you (Marcel), not an agent — the verdict is partially a judgment call, and the announcement is yours to send.

## Context Part of **Epic #411** — Cleanup. This is **CLEANUP-5**: the final gate. Re-run the legibility audit AFTER all of Epics 2–4 and CLEANUP-1..4 are done, and produce the final readiness scorecard. If 🟢🟢, the codebase is ready to send to Anja and Tobias. Per the Legibility Rubric, this re-validates ALL of C1–C10. ## Inputs - The original audit reports under `docs/audits/audit-*-report.md` (Epic 1 outputs) - The original `docs/LEGIBILITY-READINESS.md` (AUDIT-6 / #393 output) - The completion state of every other Codebase Legibility milestone issue ## Method 1. Re-walk the per-subsystem orient template (TEMPLATE-ORIENT-001 — see #387 first comment) against EACH subsystem. Don't shortcut — the whole point is verification. 2. For each rubric check, mark current status (PASS / FAIL). 3. Compare to the original audit results. Flag any check that: - WAS passing, now failing (regression — investigate before closing) - WAS failing, now passing (confirmed cleanup worked) - WAS failing, still failing (decide: do we accept it, or open a follow-up?) 4. Update `docs/audits/audit-{frontend,backend,ocr,db,rest}-report.md` IN PLACE with new scorecards (don't create new files; preserve the diff in git history) 5. Refresh `docs/LEGIBILITY-READINESS.md` with new §1 executive summary, §2 per-subsystem table, §3 aggregate scorecard, §4 remaining top-10, §5 refactor verdict (now historical), §6 evaluation verdict (the one that matters), §7 open questions. ## §6 evaluation verdict criteria - 🟢 **Ready to send to Anja and Tobias** — zero Critical findings, ≥80% of Major findings resolved or accepted - 🟡 **Ready after these specific tasks** — list them; if they're truly small, do them in this PR - 🔴 **Not ready** — list specific blockers; this kicks off another loop ## Acceptance criteria - [ ] Every audit report under `docs/audits/` has been re-scored - [ ] `docs/LEGIBILITY-READINESS.md` reflects current state, not Epic 1 state - [ ] §6 verdict is justified by reference to specific rubric findings - [ ] If §6 is 🔴, this issue does NOT close and a follow-up cycle is opened - [ ] If §6 is 🟢, the closing comment of this issue includes a one-paragraph "ready" announcement that you (Marcel) can copy into a message to Anja and Tobias - [ ] PR opened and merged ## Dependency **Hard blocked by:** every other issue in the Codebase Legibility milestone (#7). Specifically: Epic 1 (#387), Epic 2 (#394), Epic 3 (#402), Epic 4 (#406), and CLEANUP-1..4 (the four sibling issues in Epic 5). ## Definition of Done PR merged; this issue closes; the **Codebase Legibility** milestone closes; Anja and Tobias are sent the announcement. ## Dispatch Best done by you (Marcel), not an agent — the verdict is partially a judgment call, and the announcement is yours to send.

marcel added this to the Codebase Legibility milestone 2026-05-04 16:18:18 +02:00

marcel added the P1-high audit legibility labels 2026-05-04 16:18:47 +02:00

marcel referenced this issue

2026-05-04 21:05:02 +02:00

epic(legibility): polish — remove smells surfaced by audits #411

marcel referenced this issue

2026-05-04 21:05:31 +02:00

epic(legibility): polish — remove smells surfaced by audits #411

marcel commented

2026-05-04 21:05:41 +02:00

🏗️ Markus Keller — Senior Application Architect

Observations

This issue is the final gate in a well-designed five-epic sequence. The dependency graph (Epics 1→2→3→4→5→CLEANUP-5) is sound: audit before refactor, pre-flight before big-bang restructure, cleanup after restructure, scorecard last.
docs/audits/ does not yet exist in the repository. The input artifacts (the five subsystem audit reports and the original docs/LEGIBILITY-READINESS.md) that this issue depends on must be produced by the preceding issues. This issue cannot proceed until those are present — which is correct per the hard-block dependency, but it means you should verify the inputs before opening this work.
The architecture of the final scorecard (§1–§7 structure) is well-specified. The §6 criteria (zero Criticals, ≥80% Majors resolved) are measurable, which is exactly right. Verdicts that are not tied to specific rubric checks tend to drift into optimism bias.
The re-walk instruction ("don't shortcut — the whole point is verification") is architecturally correct. A delta audit that trusts the first audit's findings without re-walking will miss regressions introduced during Epic 4's big-bang restructure.

Recommendations

Verify the input precondition before starting this issue. Check that all five docs/audits/audit-{frontend,backend,ocr,db,rest}-report.md files exist and that CLEANUP-1..4 are closed. The issue correctly states this, but it bears making it the first step — agents (or you under time pressure) may attempt to run this scorecard against incomplete inputs.
Re-run the rubric mechanically, C1–C10, not by memory. The original rubric definition (in #387's first comment) is the authoritative checklist. Read it line by line against the current code after Epic 4's restructure. Module boundary rules (C3.4, C3.5, C3.6) are the most likely to have had regressions introduced during the big-bang move.
For regression tracking (step 3 of the method): "WAS passing, now failing" is the category that should block closing this issue. Do not accept it as an "unfortunate artifact of refactoring." A regression means the refactor introduced a defect.
The §6 verdict should cite specific rubric finding IDs, not just category names. "Zero Critical findings" is verified only when each formerly-Critical finding has an explicit PASS or an accepted justification.
The "best done by you (Marcel), not an agent" dispatch note is correct for exactly the right reason: §6 is partially a judgment call and the announcement message is personal. However, the mechanical re-walk of C1–C10 per subsystem is automatable and should be delegated to reduce fatigue and bias.

Open Decisions

Accepted-but-not-fixed findings: The method says "WAS failing, still failing — decide: do we accept it, or open a follow-up?" The issue doesn't define who sets the acceptance threshold or what form an acceptance justification takes. For the 🟢 verdict to be credible to Anja and Tobias, accepted findings should have a documented rationale (even one sentence), not just be silently marked as accepted. Decide: write justifications inline in the updated report, or in a separate docs/audits/accepted-findings.md?

## 🏗️ Markus Keller — Senior Application Architect ### Observations - This issue is the **final gate** in a well-designed five-epic sequence. The dependency graph (Epics 1→2→3→4→5→CLEANUP-5) is sound: audit before refactor, pre-flight before big-bang restructure, cleanup after restructure, scorecard last. - `docs/audits/` **does not yet exist** in the repository. The input artifacts (the five subsystem audit reports and the original `docs/LEGIBILITY-READINESS.md`) that this issue depends on must be produced by the preceding issues. This issue cannot proceed until those are present — which is correct per the hard-block dependency, but it means you should verify the inputs before opening this work. - The architecture of the final scorecard (§1–§7 structure) is well-specified. The §6 criteria (zero Criticals, ≥80% Majors resolved) are measurable, which is exactly right. Verdicts that are not tied to specific rubric checks tend to drift into optimism bias. - The re-walk instruction ("don't shortcut — the whole point is verification") is architecturally correct. A delta audit that trusts the first audit's findings without re-walking will miss regressions introduced during Epic 4's big-bang restructure. ### Recommendations - **Verify the input precondition before starting this issue.** Check that all five `docs/audits/audit-{frontend,backend,ocr,db,rest}-report.md` files exist and that CLEANUP-1..4 are closed. The issue correctly states this, but it bears making it the first step — agents (or you under time pressure) may attempt to run this scorecard against incomplete inputs. - **Re-run the rubric mechanically, C1–C10, not by memory.** The original rubric definition (in #387's first comment) is the authoritative checklist. Read it line by line against the current code after Epic 4's restructure. Module boundary rules (C3.4, C3.5, C3.6) are the most likely to have had regressions introduced during the big-bang move. - **For regression tracking (step 3 of the method):** "WAS passing, now failing" is the category that should block closing this issue. Do not accept it as an "unfortunate artifact of refactoring." A regression means the refactor introduced a defect. - **The §6 verdict should cite specific rubric finding IDs**, not just category names. "Zero Critical findings" is verified only when each formerly-Critical finding has an explicit PASS or an accepted justification. - The "best done by you (Marcel), not an agent" dispatch note is correct for exactly the right reason: §6 is partially a judgment call and the announcement message is personal. However, the mechanical re-walk of C1–C10 per subsystem is automatable and should be delegated to reduce fatigue and bias. ### Open Decisions - **Accepted-but-not-fixed findings:** The method says "WAS failing, still failing — decide: do we accept it, or open a follow-up?" The issue doesn't define who sets the acceptance threshold or what form an acceptance justification takes. For the 🟢 verdict to be credible to Anja and Tobias, accepted findings should have a documented rationale (even one sentence), not just be silently marked as accepted. Decide: write justifications inline in the updated report, or in a separate `docs/audits/accepted-findings.md`?

marcel referenced this issue

2026-05-04 21:05:57 +02:00

epic(legibility): polish — remove smells surfaced by audits #411

marcel commented

2026-05-04 21:06:05 +02:00

👨‍💻 Felix Brandt — Senior Fullstack Developer

Observations

The issue is process/documentation, not code — so there's limited code-quality surface to review. However, the inputs this scorecard depends on have significant implementation implications.
The five audit reports don't exist in the repo yet (docs/audits/ is absent). This is expected — Epic 1 (#387) is still open — but it means this issue is strictly blocked and should not be worked until that directory contains all five files.
The re-walk method instructs running the per-subsystem orient template against each subsystem. The orient template lives in #387's first comment. That template is the canonical checklist — any scorer skipping it and relying on memory will introduce human error.
The update-in-place instruction ("update docs/audits/audit-*-report.md IN PLACE") is the right call for diff readability in git history. What you changed between Epic 1 state and CLEANUP-5 state should be visible in git diff — don't create new files.

Recommendations

For each rubric check that changed status (FAIL→PASS or PASS→FAIL), reference the commit or PR that caused the change. Not required by the issue spec, but it makes the scorecard credible and lets Anja and Tobias spot-check the claim. A one-line note like "Fixed in REFACTOR-1 PR (#XXX)" per finding takes 30 seconds per finding.
The 🟢🟢 closing criteria should be verified against the live code, not the refactored code at branch time. Run ./mvnw clean package and npm run check and npm run lint against main at the point of writing the scorecard. Stale imports, renamed packages, and broken type generation are the failure modes most likely to surface after Epic 4.
The §6 "ready" announcement paragraph — draft it as part of closing this issue, not separately. Marcel asked that the closing comment include a copy-pasteable announcement. Draft the announcement before deciding the verdict, then verify that every sentence is actually supported by the scorecard findings. "Looks good" is not a supported sentence.
The issue says "don't shortcut — the whole point is verification." I'd reinforce this: if you run this as an agent task, give the agent the full rubric from #387 as input, not just a summary. Agents working from summaries produce summaries of summaries.

Open Decisions

None — this is a well-scoped verification task with clear inputs and outputs.

## 👨‍💻 Felix Brandt — Senior Fullstack Developer ### Observations - The issue is process/documentation, not code — so there's limited code-quality surface to review. However, the **inputs this scorecard depends on** have significant implementation implications. - The five audit reports don't exist in the repo yet (`docs/audits/` is absent). This is expected — Epic 1 (#387) is still open — but it means this issue is strictly blocked and should not be worked until that directory contains all five files. - The re-walk method instructs running the per-subsystem orient template against each subsystem. The orient template lives in #387's first comment. That template is the canonical checklist — any scorer skipping it and relying on memory will introduce human error. - The update-in-place instruction ("update `docs/audits/audit-*-report.md` IN PLACE") is the right call for diff readability in git history. What you changed between Epic 1 state and CLEANUP-5 state should be visible in `git diff` — don't create new files. ### Recommendations - **For each rubric check that changed status (FAIL→PASS or PASS→FAIL), reference the commit or PR that caused the change.** Not required by the issue spec, but it makes the scorecard credible and lets Anja and Tobias spot-check the claim. A one-line note like "Fixed in REFACTOR-1 PR (#XXX)" per finding takes 30 seconds per finding. - **The 🟢🟢 closing criteria should be verified against the live code, not the refactored code at branch time.** Run `./mvnw clean package` and `npm run check` and `npm run lint` against `main` at the point of writing the scorecard. Stale imports, renamed packages, and broken type generation are the failure modes most likely to surface after Epic 4. - **The §6 "ready" announcement paragraph** — draft it as part of closing this issue, not separately. Marcel asked that the closing comment include a copy-pasteable announcement. Draft the announcement before deciding the verdict, then verify that every sentence is actually supported by the scorecard findings. "Looks good" is not a supported sentence. - The issue says "don't shortcut — the whole point is verification." I'd reinforce this: if you run this as an agent task, give the agent the full rubric from #387 as input, not just a summary. Agents working from summaries produce summaries of summaries. ### Open Decisions None — this is a well-scoped verification task with clear inputs and outputs.

marcel referenced this issue

2026-05-04 21:06:27 +02:00

epic(legibility): polish — remove smells surfaced by audits #411

marcel commented

2026-05-04 21:06:31 +02:00

🔒 Nora "NullX" Steiner — Application Security Engineer

Observations

This is a documentation/audit gate issue — no code changes. My primary concern is whether the preceding epics (especially Epic 4's big-bang package restructure) may have introduced security regressions that a legibility-focused audit rubric won't catch.
Epic 4 moves the entire backend from controller/, service/, repository/ flat packages into per-domain packages. Security configuration lives in security/ — that package moves too. Any Spring Security bean ordering, @RequirePermission AOP wiring, or SecurityConfig import that breaks silently during the move won't necessarily surface as a compilation error. It surfaces as an open endpoint.
The rubric (C1–C10) is described as legibility-focused, not security-focused. It likely covers things like naming clarity, boundary compliance, and documentation. It may not specifically re-audit auth endpoint coverage after the restructure.
docs/LEGIBILITY-READINESS.md (the original AUDIT-6 output from #393) doesn't exist yet in the repo. This scorecard will be the first time the document is created — not refreshed. The update-in-place instruction makes sense for the five subsystem reports, but there is no §6 baseline to compare against from AUDIT-6 yet.

Recommendations

Add one explicit security check to the CLEANUP-5 re-walk: After Epic 4's package restructure, verify that @RequirePermission enforcement still works end-to-end. The simplest way: run the existing @WebMvcTest security tests and confirm they pass. If any endpoint that previously returned 403 for a viewer now returns 200, that is a Critical finding that must block the 🟢 verdict.
Check that SecurityConfig imports survived the restructure. @Import({SecurityConfig.class, PermissionAspect.class}) in @WebMvcTest slices references class paths. If the class moved packages, tests that compiled against the old path may still pass if Spring picks up the bean from the new path — but this depends on scan configuration. Verify explicitly.
Actuator exposure: The security guide in docs/security-guide.md exists. If CLEANUP-5 updates the readiness scorecard, confirm that the actuator blocking configuration (springdoc.api-docs.enabled: false for production, /actuator/* blocked in Caddy) survived Epic 4 untouched. This is a config file, not application code, so it won't be moved by the refactor — but it's worth one explicit check.
The closing "ready" announcement will go to Anja (a Java backend dev) and Tobias (PM-with-CS). Neither of them is a security reviewer. Make sure any security findings that were accepted (not fixed) are recorded in the scorecard with explicit justification so they can make informed decisions if they later review the security posture.

Open Decisions

None. This is a verification issue. Security concerns are about what to check during the walk, not about decisions to make.

## 🔒 Nora "NullX" Steiner — Application Security Engineer ### Observations - This is a documentation/audit gate issue — no code changes. My primary concern is whether the preceding epics (especially Epic 4's big-bang package restructure) may have introduced security regressions that a legibility-focused audit rubric won't catch. - Epic 4 moves the entire backend from `controller/`, `service/`, `repository/` flat packages into per-domain packages. **Security configuration lives in `security/`** — that package moves too. Any Spring Security bean ordering, `@RequirePermission` AOP wiring, or `SecurityConfig` import that breaks silently during the move won't necessarily surface as a compilation error. It surfaces as an open endpoint. - The rubric (C1–C10) is described as legibility-focused, not security-focused. It likely covers things like naming clarity, boundary compliance, and documentation. It may not specifically re-audit auth endpoint coverage after the restructure. - `docs/LEGIBILITY-READINESS.md` (the original AUDIT-6 output from #393) doesn't exist yet in the repo. This scorecard will be the first time the document is created — not refreshed. The update-in-place instruction makes sense for the five subsystem reports, but there is no §6 baseline to compare against from AUDIT-6 yet. ### Recommendations - **Add one explicit security check to the CLEANUP-5 re-walk:** After Epic 4's package restructure, verify that `@RequirePermission` enforcement still works end-to-end. The simplest way: run the existing `@WebMvcTest` security tests and confirm they pass. If any endpoint that previously returned 403 for a viewer now returns 200, that is a Critical finding that must block the 🟢 verdict. - **Check that `SecurityConfig` imports survived the restructure.** `@Import({SecurityConfig.class, PermissionAspect.class})` in `@WebMvcTest` slices references class paths. If the class moved packages, tests that compiled against the old path may still pass if Spring picks up the bean from the new path — but this depends on scan configuration. Verify explicitly. - **Actuator exposure:** The security guide in `docs/security-guide.md` exists. If CLEANUP-5 updates the readiness scorecard, confirm that the actuator blocking configuration (`springdoc.api-docs.enabled: false` for production, `/actuator/*` blocked in Caddy) survived Epic 4 untouched. This is a config file, not application code, so it won't be moved by the refactor — but it's worth one explicit check. - The closing "ready" announcement will go to Anja (a Java backend dev) and Tobias (PM-with-CS). Neither of them is a security reviewer. Make sure any security findings that were accepted (not fixed) are recorded in the scorecard with explicit justification so they can make informed decisions if they later review the security posture. ### Open Decisions None. This is a verification issue. Security concerns are about what to check during the walk, not about decisions to make.

marcel commented

2026-05-04 21:06:53 +02:00

🧪 Sara Holt — QA Engineer & Test Strategist

Observations

The acceptance criteria are well-formed and measurable — exactly what I need from a DoD perspective. The §6 criterion ("zero Critical findings, ≥80% of Major findings resolved or accepted") is testable, unlike typical "it looks good" completion criteria.
Epic 3 (#402) — the pre-flight testing epic — must complete before this scorecard is meaningful. Epic 3 verifies that tests are trustworthy (mutation testing, filling tautological test gaps, E2E journey coverage). If Epic 3 is still open when CLEANUP-5 runs, the "full test suite green" claim in the scorecard is not well-supported.
The re-walk instruction is correct QA practice: you don't trust a baseline report from before major structural changes. The full C1–C10 re-walk is the equivalent of running the full test suite after a refactor — you don't skip tests because they passed before.
The issue specifies updating the five subsystem reports "IN PLACE." From a QA perspective, this is the right approach: the git diff shows exactly which findings changed status, which is the audit trail. However, it also means the five report files must exist before this issue can run — and they don't exist yet in the repo.

Recommendations

Before marking this issue in-progress, run a preflight checklist: (a) docs/audits/ exists and contains all five report files, (b) CLEANUP-1..4 are closed, (c) Epic 3's mutation testing results are documented. If any of these are missing, the scorecard produced will be incomplete.
For each finding that transitions FAIL→PASS: cite the specific commit or PR. "Tests now pass" is not sufficient. "Tests pass, specifically the ArchUnit boundary test added in REFACTOR-3 PR (#XXX)" is verifiable. Anja or Tobias can check the referenced PR.
For each finding that is "accepted" (WAS failing, still failing, accepted): document what the impact is if the finding is never fixed. "This is accepted because it's cosmetic and non-blocking" is a valid justification. "This is accepted" with no rationale is not — it looks like a skip.
The closing comment should state the before/after counts explicitly: "Original audit: N Critical, M Major findings. Current state: 0 Critical, K Major findings resolved, L Major findings accepted. §6 verdict: 🟢." This gives Anja and Tobias a concrete comparison, not just a verdict.
If §6 is 🔴: the issue correctly states it does NOT close. Verify that the follow-up cycle is opened as a new issue before closing — don't leave a 🔴 verdict with no action path.

Open Decisions

Who determines "accepted" for a Major finding? The issue says "decide: do we accept it, or open a follow-up?" but doesn't name the decision owner. For solo development this is you (Marcel) — but for the announcement to Anja/Tobias to be credible, accepted Majors should have at least one sentence of written justification that they could read. Is that justification inline in the report, or in a separate comment on this issue?

## 🧪 Sara Holt — QA Engineer & Test Strategist ### Observations - The acceptance criteria are well-formed and measurable — exactly what I need from a DoD perspective. The §6 criterion ("zero Critical findings, ≥80% of Major findings resolved or accepted") is testable, unlike typical "it looks good" completion criteria. - Epic 3 (#402) — the pre-flight testing epic — must complete before this scorecard is meaningful. Epic 3 verifies that tests are trustworthy (mutation testing, filling tautological test gaps, E2E journey coverage). If Epic 3 is still open when CLEANUP-5 runs, the "full test suite green" claim in the scorecard is not well-supported. - The re-walk instruction is correct QA practice: you don't trust a baseline report from before major structural changes. The full C1–C10 re-walk is the equivalent of running the full test suite after a refactor — you don't skip tests because they passed before. - The issue specifies updating the five subsystem reports "IN PLACE." From a QA perspective, this is the right approach: the git diff shows exactly which findings changed status, which is the audit trail. However, it also means the five report files must exist before this issue can run — and they don't exist yet in the repo. ### Recommendations - **Before marking this issue in-progress, run a preflight checklist:** (a) `docs/audits/` exists and contains all five report files, (b) CLEANUP-1..4 are closed, (c) Epic 3's mutation testing results are documented. If any of these are missing, the scorecard produced will be incomplete. - **For each finding that transitions FAIL→PASS: cite the specific commit or PR.** "Tests now pass" is not sufficient. "Tests pass, specifically the ArchUnit boundary test added in REFACTOR-3 PR (#XXX)" is verifiable. Anja or Tobias can check the referenced PR. - **For each finding that is "accepted" (WAS failing, still failing, accepted):** document what the impact is if the finding is never fixed. "This is accepted because it's cosmetic and non-blocking" is a valid justification. "This is accepted" with no rationale is not — it looks like a skip. - **The closing comment should state the before/after counts explicitly:** "Original audit: N Critical, M Major findings. Current state: 0 Critical, K Major findings resolved, L Major findings accepted. §6 verdict: 🟢." This gives Anja and Tobias a concrete comparison, not just a verdict. - **If §6 is 🔴:** the issue correctly states it does NOT close. Verify that the follow-up cycle is opened as a new issue before closing — don't leave a 🔴 verdict with no action path. ### Open Decisions - **Who determines "accepted" for a Major finding?** The issue says "decide: do we accept it, or open a follow-up?" but doesn't name the decision owner. For solo development this is you (Marcel) — but for the announcement to Anja/Tobias to be credible, accepted Majors should have at least one sentence of written justification that they could read. Is that justification inline in the report, or in a separate comment on this issue?

marcel referenced this issue

2026-05-04 21:07:13 +02:00

epic(legibility): polish — remove smells surfaced by audits #411

marcel commented

2026-05-04 21:07:17 +02:00

🎨 Leonie Voss — UX Designer & Accessibility Strategist

Observations

This issue is entirely about documentation, audit methodology, and codebase health — no UI changes. My direct design concerns are minimal here. That said, the audience for the output matters to me: Anja and Tobias will read docs/LEGIBILITY-READINESS.md and form a first impression of the codebase. The document's own legibility and clarity is part of what makes the handoff successful.
The §1 executive summary ("one paragraph: what state the codebase is in for human evaluation, written so Anja and Tobias could read it cold") is a UX challenge, not a technical one. The paragraph must be written at PM-with-CS reading level for Tobias, not at Java-developer level for Anja.
The §6 "ready" announcement paragraph that closes this issue is the message Marcel will copy into a real communication to real people. It should be warm, concrete, and honest — not a list of rubric scores.

Recommendations

Write the executive summary (§1) for Tobias first, then check it reads correctly for Anja. Tobias is a "PM-with-CS" — he understands code structure but may not know what "layer-based vs domain-based packaging" means without a one-sentence explanation. Avoid technical jargon in §1; save it for §2–§4.
The §6 verdict box should be the first thing both readers see, not buried at section 6. Consider adding a one-line "TL;DR" at the very top of docs/LEGIBILITY-READINESS.md that states the §6 verdict directly. Readers who want depth will read on; readers who want the bottom line get it immediately.
The closing comment "ready announcement" — the issue says Marcel should copy it into a message to Anja and Tobias. Write it in first person, not in rubric language. "The codebase is ready for you to review — here's what you'll find when you open it" is more inviting than "§6 verdict: 🟢, 0 Critical findings, 83% Major findings resolved."
For documents that Anja and Tobias will actually read (README, ARCHITECTURE, GLOSSARY — from Epic 2): if those docs were produced by Epic 2 before this scorecard, the scorecard should call out specifically whether those orientation docs are complete and readable. That's what will determine Anja and Tobias's first 10 minutes with the codebase.

Open Decisions

None from a UX perspective. The output quality depends on execution, not on architectural choices.

## 🎨 Leonie Voss — UX Designer & Accessibility Strategist ### Observations - This issue is entirely about documentation, audit methodology, and codebase health — no UI changes. My direct design concerns are minimal here. That said, the **audience for the output** matters to me: Anja and Tobias will read `docs/LEGIBILITY-READINESS.md` and form a first impression of the codebase. The document's own legibility and clarity is part of what makes the handoff successful. - The §1 executive summary ("one paragraph: what state the codebase is in for human evaluation, written so Anja and Tobias could read it cold") is a UX challenge, not a technical one. The paragraph must be written at PM-with-CS reading level for Tobias, not at Java-developer level for Anja. - The §6 "ready" announcement paragraph that closes this issue is the message Marcel will copy into a real communication to real people. It should be warm, concrete, and honest — not a list of rubric scores. ### Recommendations - **Write the executive summary (§1) for Tobias first, then check it reads correctly for Anja.** Tobias is a "PM-with-CS" — he understands code structure but may not know what "layer-based vs domain-based packaging" means without a one-sentence explanation. Avoid technical jargon in §1; save it for §2–§4. - **The §6 verdict box should be the first thing both readers see, not buried at section 6.** Consider adding a one-line "TL;DR" at the very top of `docs/LEGIBILITY-READINESS.md` that states the §6 verdict directly. Readers who want depth will read on; readers who want the bottom line get it immediately. - **The closing comment "ready announcement"** — the issue says Marcel should copy it into a message to Anja and Tobias. Write it in first person, not in rubric language. "The codebase is ready for you to review — here's what you'll find when you open it" is more inviting than "§6 verdict: 🟢, 0 Critical findings, 83% Major findings resolved." - **For documents that Anja and Tobias will actually read** (README, ARCHITECTURE, GLOSSARY — from Epic 2): if those docs were produced by Epic 2 before this scorecard, the scorecard should call out specifically whether those orientation docs are complete and readable. That's what will determine Anja and Tobias's first 10 minutes with the codebase. ### Open Decisions None from a UX perspective. The output quality depends on execution, not on architectural choices.

marcel commented

2026-05-04 21:07:33 +02:00

🚀 Tobias Wendt — DevOps & Platform Engineer

Observations

No infrastructure changes in this issue — it's a documentation and audit gate. My angle is process reliability: does this issue have the right gates to not produce a false-positive 🟢 verdict?
The blocking dependency ("hard blocked by every other issue in the milestone") is correct but not enforced by Gitea automation. A human (or agent) can start this issue before its blockers close. The "Dispatch: best done by you (Marcel), not an agent" note mitigates this, but manual discipline is weaker than a gate.
The "update docs/audits/ IN PLACE" instruction preserves git history correctly. That is the right approach for auditability — the git diff between the Epic 1 commit and the CLEANUP-5 commit is the change log for the entire Codebase Legibility effort.
docs/audits/ does not exist on main yet. The branch for this work must be cut from a state where all five predecessor issues' artifacts have been merged. Cutting the CLEANUP-5 branch from an incomplete state produces a scorecard with incomplete inputs.

Recommendations

Verify the branch base before starting. Before creating the CLEANUP-5 working branch: ls docs/audits/ should list all five report files. If it doesn't, wait. The five report files are the only inputs this issue consumes — don't start without them.
The PR for this issue should reference all preceding milestone issues. The CLEANUP-5 PR is the final PR in the Codebase Legibility milestone. Its description should list the full chain: "Closes #416. Completes Codebase Legibility milestone (#7). Preceded by #387, #394, #402, #406, #411." This makes the history readable in the PR list.
The closing comment "one paragraph announcement" should be drafted and included as the PR description's last section, not just in the issue comment. That way the announcement is preserved in the PR history as well.
If the §6 verdict is 🔴: per the issue spec, this issue does NOT close and a follow-up cycle is opened. Make sure the follow-up cycle issue is opened before the PR is merged so there's no gap in the audit trail. Don't merge a 🔴 scorecard without an immediate follow-up issue.
The milestone (Codebase Legibility, #7) closes when this issue closes. Confirm all other milestone issues are actually closed before merging, not just "in review." A milestone with one open issue and a 🟢 scorecard is contradictory.

Open Decisions

None. This is a gate issue with clear inputs, clear outputs, and clear completion criteria.

## 🚀 Tobias Wendt — DevOps & Platform Engineer ### Observations - No infrastructure changes in this issue — it's a documentation and audit gate. My angle is process reliability: does this issue have the right gates to not produce a false-positive 🟢 verdict? - The blocking dependency ("hard blocked by every other issue in the milestone") is correct but not enforced by Gitea automation. A human (or agent) can start this issue before its blockers close. The "Dispatch: best done by you (Marcel), not an agent" note mitigates this, but manual discipline is weaker than a gate. - The "update `docs/audits/` IN PLACE" instruction preserves git history correctly. That is the right approach for auditability — the git diff between the Epic 1 commit and the CLEANUP-5 commit is the change log for the entire Codebase Legibility effort. - `docs/audits/` does not exist on `main` yet. The branch for this work must be cut from a state where all five predecessor issues' artifacts have been merged. Cutting the CLEANUP-5 branch from an incomplete state produces a scorecard with incomplete inputs. ### Recommendations - **Verify the branch base before starting.** Before creating the CLEANUP-5 working branch: `ls docs/audits/` should list all five report files. If it doesn't, wait. The five report files are the only inputs this issue consumes — don't start without them. - **The PR for this issue should reference all preceding milestone issues.** The CLEANUP-5 PR is the final PR in the Codebase Legibility milestone. Its description should list the full chain: "Closes #416. Completes Codebase Legibility milestone (#7). Preceded by #387, #394, #402, #406, #411." This makes the history readable in the PR list. - **The closing comment "one paragraph announcement" should be drafted and included as the PR description's last section**, not just in the issue comment. That way the announcement is preserved in the PR history as well. - **If the §6 verdict is 🔴:** per the issue spec, this issue does NOT close and a follow-up cycle is opened. Make sure the follow-up cycle issue is opened before the PR is merged so there's no gap in the audit trail. Don't merge a 🔴 scorecard without an immediate follow-up issue. - The milestone (Codebase Legibility, #7) closes when this issue closes. Confirm all other milestone issues are actually closed before merging, not just "in review." A milestone with one open issue and a 🟢 scorecard is contradictory. ### Open Decisions None. This is a gate issue with clear inputs, clear outputs, and clear completion criteria.

marcel commented

2026-05-04 21:07:38 +02:00

📋 Elicit — Requirements Engineer

Observations

This issue is exceptionally well-specified for a solo-developer workflow. The §1–§7 structure, the verdict criteria, and the "if 🔴 do NOT close" rule all demonstrate prior requirements discipline that is rare in developer-led projects.
One gap in acceptance criteria: the issue says "§6 verdict is justified by reference to specific rubric findings" — but it doesn't define what "specific rubric finding reference" means in practice. Is it a finding ID (e.g., C3.4.FAIL), a section heading, or a free-text description? Ambiguity here risks a verdict that says "justified" but can't be traced.
The issue correctly identifies that this is a judgment call ("Dispatch: best done by you"), but the judgment criteria for §6 are actually fully specified: zero Criticals, ≥80% Majors. The only actual judgment is the acceptance justifications for remaining Majors. This is a narrow judgment call, not a broad one.
The acceptance criterion "If §6 is 🔴, this issue does NOT close and a follow-up cycle is opened" is correct but incomplete: it doesn't specify what the follow-up cycle issue looks like. Without that specification, a 🔴 verdict could lead to a vague "do more work" issue rather than a precise remediation plan.

Recommendations

Define a minimal "justification" format for accepted findings. Suggested: FINDING-ID: [finding text] — ACCEPTED because [one sentence rationale]. Impact if never fixed: [one sentence]. This is 2–3 sentences per finding, takes 5 minutes per finding, and makes the scorecard defensible to Anja and Tobias.
Clarify what constitutes "80% of Major findings resolved." Does "resolved" mean (a) a PR was merged that addresses it, or (b) the rubric check now passes, or (c) the finding appears in the updated report with a PASS status? These are different standards. Recommendation: (b) — the rubric check passes — is the only verifiable standard.
The closing comment announcement paragraph is underspecified. The issue says "a one-paragraph 'ready' announcement that you (Marcel) can copy into a message to Anja and Tobias." It doesn't say what the announcement must contain. Suggested minimum: what the codebase contains, what state it's in, how to run it locally, and what Anja/Tobias are expected to do (evaluate? contribute? review?). Without this minimum content, the announcement could be too sparse to be actionable.
The "open follow-up cycle" for a 🔴 verdict should produce an issue with the same structure as CLEANUP-5 — not a vague "fix the remaining findings" issue. Consider noting this in the issue text so a future agent or Marcel-under-time-pressure doesn't create an underspecified follow-up.

Open Decisions

Accepted findings: inline in the report or in a separate register? Inline (in the updated docs/audits/audit-*.md files) preserves co-location of finding + justification. A separate register (e.g., an accepted-findings.md or a comment on this issue) is easier to scan but splits the information. Both are valid — pick one and be consistent. (Shared with Markus and Sara's observations.)

## 📋 Elicit — Requirements Engineer ### Observations - This issue is exceptionally well-specified for a solo-developer workflow. The §1–§7 structure, the verdict criteria, and the "if 🔴 do NOT close" rule all demonstrate prior requirements discipline that is rare in developer-led projects. - One gap in acceptance criteria: the issue says "§6 verdict is justified by reference to specific rubric findings" — but it doesn't define what "specific rubric finding reference" means in practice. Is it a finding ID (e.g., C3.4.FAIL), a section heading, or a free-text description? Ambiguity here risks a verdict that says "justified" but can't be traced. - The issue correctly identifies that this is a **judgment call** ("Dispatch: best done by you"), but the judgment criteria for §6 are actually fully specified: zero Criticals, ≥80% Majors. The only actual judgment is the acceptance justifications for remaining Majors. This is a narrow judgment call, not a broad one. - The acceptance criterion "If §6 is 🔴, this issue does NOT close and a follow-up cycle is opened" is correct but incomplete: it doesn't specify what the follow-up cycle issue looks like. Without that specification, a 🔴 verdict could lead to a vague "do more work" issue rather than a precise remediation plan. ### Recommendations - **Define a minimal "justification" format for accepted findings.** Suggested: `FINDING-ID: [finding text] — ACCEPTED because [one sentence rationale]. Impact if never fixed: [one sentence].` This is 2–3 sentences per finding, takes 5 minutes per finding, and makes the scorecard defensible to Anja and Tobias. - **Clarify what constitutes "80% of Major findings resolved."** Does "resolved" mean (a) a PR was merged that addresses it, or (b) the rubric check now passes, or (c) the finding appears in the updated report with a PASS status? These are different standards. Recommendation: (b) — the rubric check passes — is the only verifiable standard. - **The closing comment announcement paragraph is underspecified.** The issue says "a one-paragraph 'ready' announcement that you (Marcel) can copy into a message to Anja and Tobias." It doesn't say what the announcement must contain. Suggested minimum: what the codebase contains, what state it's in, how to run it locally, and what Anja/Tobias are expected to do (evaluate? contribute? review?). Without this minimum content, the announcement could be too sparse to be actionable. - **The "open follow-up cycle" for a 🔴 verdict should produce an issue with the same structure as CLEANUP-5** — not a vague "fix the remaining findings" issue. Consider noting this in the issue text so a future agent or Marcel-under-time-pressure doesn't create an underspecified follow-up. ### Open Decisions - **Accepted findings: inline in the report or in a separate register?** Inline (in the updated `docs/audits/audit-*.md` files) preserves co-location of finding + justification. A separate register (e.g., an `accepted-findings.md` or a comment on this issue) is easier to scan but splits the information. Both are valid — pick one and be consistent. _(Shared with Markus and Sara's observations.)_

marcel commented

2026-05-04 21:07:51 +02:00

🗳️ Decision Queue — Action Required

2 decisions need your input before implementation starts.

Process / Documentation

Where do accepted-but-not-fixed findings live? The method says "WAS failing, still failing — decide: do we accept it, or open a follow-up?" but doesn't specify where the acceptance justification is recorded. Options: (a) inline in each updated docs/audits/audit-*.md — keeps finding and rationale co-located, visible in git diff; (b) a separate docs/audits/accepted-findings.md — easier to scan in one place but splits information. Pick one and be consistent — the verdict's credibility to Anja and Tobias depends on it. (Raised by: Markus, Sara, Elicit)
What does "80% of Major findings resolved" mean in practice? Three possible standards: (a) a PR was merged that addresses the finding, (b) the rubric check now PASS-scores on a live re-walk, or (c) the finding is listed as PASS in the updated report. These produce different verdicts for borderline cases. Recommendation: use (b) — the rubric check passes on a live re-walk — as the only verifiable standard, since (a) and (c) can drift. If you accept a different standard, write it into the updated docs/LEGIBILITY-READINESS.md so the reasoning is on record. (Raised by: Elicit, Sara)

## 🗳️ Decision Queue — Action Required _2 decisions need your input before implementation starts._ ### Process / Documentation - **Where do accepted-but-not-fixed findings live?** The method says "WAS failing, still failing — decide: do we accept it, or open a follow-up?" but doesn't specify where the acceptance justification is recorded. Options: (a) **inline in each updated `docs/audits/audit-*.md`** — keeps finding and rationale co-located, visible in git diff; (b) **a separate `docs/audits/accepted-findings.md`** — easier to scan in one place but splits information. Pick one and be consistent — the verdict's credibility to Anja and Tobias depends on it. _(Raised by: Markus, Sara, Elicit)_ - **What does "80% of Major findings resolved" mean in practice?** Three possible standards: (a) a PR was merged that addresses the finding, (b) the rubric check now PASS-scores on a live re-walk, or (c) the finding is listed as PASS in the updated report. These produce different verdicts for borderline cases. Recommendation: use (b) — the rubric check passes on a live re-walk — as the only verifiable standard, since (a) and (c) can drift. If you accept a different standard, write it into the updated `docs/LEGIBILITY-READINESS.md` so the reasoning is on record. _(Raised by: Elicit, Sara)_

marcel closed this issue

2026-05-07 15:22:38 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#416