From c2389f871d5af3e0ce1e53b3c13d8ea8ec7a544b Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sat, 31 Oct 2026 14:09:54 +0100 Subject: [PATCH] Record the comprehension check: overall 6.50 then 6.38, under the 7.0 floor; the README's REQUIRE_SECURE_SECRETS drift is filed as item 56 --- docs/comprehension-history.md | 68 +++++++++++++++++++++++++++++++++++ todo.md | 14 +++++++- 2 files changed, 81 insertions(+), 1 deletion(-) diff --git a/docs/comprehension-history.md b/docs/comprehension-history.md index 9e4e47f..49719f0 100644 --- a/docs/comprehension-history.md +++ b/docs/comprehension-history.md @@ -222,3 +222,71 @@ Inherited architect, would restructure first: - Locality, Overall: `src/http/app.ts:185` `handleRequest`: the most concerns and the highest complexity, already grandfathered, and every request-wide concern lands in it - Shape, Navigation: `src/ui/stylesheet-floor.ts:15` `FLOOR`: the 3am rule's home is a test-only module under `ui/` - Shape: `src/auth/routes.ts:275` `buildAuthRoutes`: the 19-module `src/auth/` mixes six concerns, and this file with `flow-view.ts` is where the next flow lands + +## 2026-10-31T13:06:16Z, PR #202 at 8e73d16 + +| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | +|---|---|---|---|---|---| +| Junior A | 7 | 6 | 6.5 | 6.5 | 6.5 | +| Mid A | 7 | 6 | 6 | 6.5 | 6.5 | +| Maintainability senior | 7 | 6 | 6 | 6.5 | 6.5 | +| Inherited architect | 6.5 | 6 | 6 | 6.5 | 6.5 | +| Mean | 6.88 | 6.00 | 6.13 | 6.50 | 6.50 | + +Junior A, hardest first: + +- Locality, Overall: `src/http/app.ts:185` `handleRequest`: about 165 lines in a fixed order that only a top-to-bottom read shows +- Self-sufficiency, Shape: `src/auth/login.ts:40` `readPermissions`: the comment says `#members` where the code uses `granted` +- Self-sufficiency: `src/plugin-host/settings.ts:35` `SettingsOf`: nested conditional types that need the charter's rule to decode + +Mid A, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: complexity 43 inside the 318-line `createApp` closure, and `switchBase` reads `builtinRoutes` declared 60 lines later +- Locality, Shape: `src/ui/stylesheet-floor.ts:119` `positive`: a regex CSS walker whose how stayed opaque +- Self-sufficiency: `src/auth/bootstrap.ts:31` `permissionTuple`: the comment says `#members` where the code uses `granted` + +Maintainability senior, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: 167 lines and complexity 43 mixing twelve concerns whose order no type expresses +- Locality: `src/ui/stylesheet-floor.ts:119` `positive`: a hand-rolled regex CSS scanner traced by hand +- Self-sufficiency: `src/auth/gate.ts:13` `allows`: an empty gate is allowed, and the reason lives only in AGENTS.md + +Inherited architect, would restructure first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: the largest hub, where every request-wide concern lands +- Shape, Navigation: `src/auth/routes.ts:275` `buildAuthRoutes`: the 19-module `src/auth/` mixes four concerns with no sub-folder +- Shape, Navigation: `src/ui/stylesheet-floor.ts:30` `floorViolations`: test tooling sits among the runtime UI modules + +## 2026-10-31T13:06:21Z, PR #202 rerun at 8e73d16 + +| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | +|---|---|---|---|---|---| +| Junior A | 7 | 5.5 | 6 | 6 | 6 | +| Mid A | 7 | 6 | 6 | 6 | 6.5 | +| Maintainability senior | 7 | 6 | 6 | 6 | 6.5 | +| Inherited architect | 7 | 5.5 | 6 | 7 | 6.5 | +| Mean | 7.00 | 5.75 | 6.00 | 6.25 | 6.38 | + +Junior A, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: closures over request state in a 318-line `createApp`, and it stayed opaque +- Self-sufficiency: `src/auth/routes.ts:58` `flowFailure`: the Kratos status semantics live outside the repo +- Self-sufficiency, Shape: `src/auth/login.ts:45` `readPermissions`: the comment says `#members` where the code uses `granted` + +Mid A, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: one pipeline whose steps mutate what later steps read +- Locality: `src/ui/stylesheet-floor.ts:119` `positive`: traced by hand +- Self-sufficiency, Shape: `src/auth/login.ts:45` `readPermissions`: the comment says `#members` where the code uses `granted` + +Maintainability senior, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: an unstated, load-bearing step order in shared closure state +- Locality: `src/ui/stylesheet-floor.ts:119` `positive`: a hand-rolled CSS scanner built on lookbehind regexes +- Self-sufficiency, Shape: `src/auth/bootstrap.ts:31` `permissionTuple`: the comment is false on the security-relevant path + +Inherited architect, would restructure first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: stage order lives only in line order, in a grandfathered complexity-43 function +- Shape, Navigation: `src/auth/routes.ts:275` `buildAuthRoutes`: 19 flat modules in `src/auth/`, and the next flow lands here +- Shape, Navigation: `src/ui/stylesheet-floor.ts:15` `FLOOR`: the 3am rule's home is a test-only module under `ui/` diff --git a/todo.md b/todo.md index 9426548..ec3053a 100644 --- a/todo.md +++ b/todo.md @@ -6,12 +6,13 @@ `Bar = 1` -`Next ID = 56` +`Next ID = 57` ## Items | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score | |---|---|---|---|---|---|---|---|---|---|---|---| +| 56 | 0.4.22 | | | **Correct the README's two statements that `REQUIRE_SECURE_SECRETS` guards only `CSRF_SECRET`.** | 1 | 2 | 1 | 2 | 1 | code health by 2 | 14.4 | | 19 | 0.5.0 | | question | **Run the documented Docker commands on macOS and fix whatever misbehaves.** | 2 | 2 | 1 | 3 | 3 | 1 by 3 | 3.3 | | 16 | 0.5.0 | | question | **Decide whether the single Keto `Resource` namespace splits into per-domain namespaces.** | 3 | 2 | 3 | 6 | 6 | 7 by 2 | 0.5 | | 48 | 0.5.0 | | | **Correct the Keto tuple in the `login.ts` and `bootstrap.ts` comments to the `granted` relation the code writes.** | 1 | 1 | 1 | 1 | 1 | code health by 4 | 28.7 | @@ -33,6 +34,17 @@ ## Details +### 56. Correct the README's two statements that `REQUIRE_SECURE_SECRETS` guards only `CSRF_SECRET`. + +README → What you must supply (about `:1275`: "refuses to boot on a missing or throwaway +`CSRF_SECRET` and **nothing else**") and README → Security model (about `:1442`: +"`REQUIRE_SECURE_SECRETS` guards only `CSRF_SECRET`") contradict the Configuration table row (about +`:1216`), `src/config.ts:59` and `:190`, and `src/plugin-host/settings.ts`. The flag also refuses a +missing or throwaway `PLUGIN_DB_SECRET` once `PLUGIN_DB_URL` is set, and every plugin setting +declared `secret`. An operator following the checklist underrates the toggle. Make both passages say +what the flag enforces by pointing to the table row, its one home. Four comprehension seats raised it +independently. Markdown only. + ### 19. Run the documented Docker commands on macOS and fix whatever misbehaves. Needs a Mac. Two suspects, both from `--user "$(id -u):$(id -g)"`: a macOS `id -g` is `20`, which is