diff --git a/backend/README.md b/backend/README.md index a2423a5..9923935 100644 --- a/backend/README.md +++ b/backend/README.md @@ -15,7 +15,7 @@ status codes and error envelope are production-shaped. covers it, see `docker-compose.yml`) does **not** lose data. Delete the file to reset demo data back to empty, the same state a fresh clone starts from. This is a deliberate, right-sized choice for a POC (SQLite, no external DB service) — see -the durable-persistence design note in `docs/project/backlog/`. +`docs/project/backlog/WP-22-durable-persistence.md`. ## Run diff --git a/backend/src/BigRegister.Api/Domain/Letters/LetterHtml.cs b/backend/src/BigRegister.Api/Domain/Letters/LetterHtml.cs index 92d2ccd..9c3541d 100644 --- a/backend/src/BigRegister.Api/Domain/Letters/LetterHtml.cs +++ b/backend/src/BigRegister.Api/Domain/Letters/LetterHtml.cs @@ -151,9 +151,8 @@ public static class LetterHtml private static string EncLines(string s) => Enc(s).Replace("\n", "
"); // Walks up from the running assembly's own directory (NOT the process cwd, which - // varies by how `dotnet run`/docker/tests invoke it — see the letter-preview-html design - // note in docs/project/backlog/) until - // it finds `public/letter.css`. docker-compose.yml bind-mounts `./public` under the + // varies by how `dotnet run`/docker/tests invoke it — see + // docs/project/backlog/WP-25-letter-preview-html.md) until it finds `public/letter.css`. docker-compose.yml bind-mounts `./public` under the // api container's `/src` for exactly this walk to resolve there too. private static string FindLetterCss() { diff --git a/docs/project/readable-codebase/RD-19-ticket-refs-backend.md b/docs/project/readable-codebase/RD-19-ticket-refs-backend.md index 519179c..5caba89 100644 --- a/docs/project/readable-codebase/RD-19-ticket-refs-backend.md +++ b/docs/project/readable-codebase/RD-19-ticket-refs-backend.md @@ -25,10 +25,22 @@ Strip the reference, keep the sentence. No behaviour changes. ## Decisions (pre-made, don't relitigate) -1. **Nothing in `backend/` is exempt. Strip all 370.** Unlike the front end, no backend file - disables a check by naming the ticket that removes it — verified against - `pragma warning disable`, `Skip =`, `NoWarn` and `SuppressMessage`, none of which carries a - reference. Keep all 40 `ADR-000x` references; that count must not move. +1. **Strip all 370 except two.** No backend file disables a check by naming the ticket that + removes it — verified against `pragma warning disable`, `Skip =`, `NoWarn` and + `SuppressMessage`, none of which carries a reference. Keep all 40 `ADR-000x` references; that + count must not move. + + **Corrected after the ticket ran.** The original text said "nothing is exempt", and it was + wrong. Two references are part of a path to a document that still exists: + + | Site | Reference | + | ---------------------------------- | --------------------------------------------------- | + | `backend/README.md:18` | `docs/project/backlog/WP-22-durable-persistence.md` | + | `Domain/Letters/LetterHtml.cs:153` | `docs/project/backlog/WP-25-letter-preview-html.md` | + + RD-18 exempted this same class of reference (`a11y.mdx:68`). A path that resolves is a + pointer, not provenance. Stripping the number breaks the path, and describing the file in + prose instead makes the reader search for it. 2. **`public/letter.css` and `LetterHtml.golden.html` change together, or the build goes red.** `LetterHtml.cs:161` finds `public/letter.css` at run time and **inlines it** into the @@ -96,7 +108,14 @@ Measured against the tree before handover. `git grep -o … | wc -l` counts **oc `git grep -c` counts lines and would give a different, wrong number. ```bash -git grep -oE "\b(WP|RB)-[0-9]+" -- backend public/letter.css | wc -l # is 373 -> MUST be 0 +git grep -oE "\b(WP|RB)-[0-9]+" -- backend public/letter.css | wc -l # is 373 -> MUST be 2 +``` + +The two survivors are the document paths in decision 1: + +```bash +git grep -oE "\b(WP|RB)-[0-9]+" -- backend/README.md \ + backend/src/BigRegister.Api/Domain/Letters/LetterHtml.cs | wc -l # MUST be 2 ``` The ADR references survive, and the sweep leaves no damaged prose: diff --git a/docs/project/readable-codebase/README.md b/docs/project/readable-codebase/README.md index 5da9302..1d2137f 100644 --- a/docs/project/readable-codebase/README.md +++ b/docs/project/readable-codebase/README.md @@ -198,6 +198,15 @@ Three rules when you write a ticket file, because the agent reads its ticket and on word boundaries**: `git grep -w machineRemoteData` and `git grep -nE "(^|[^a-zA-Z])LoadLifecycle\b"`. + - RD-19 asserted the backend sweep must reach **0** references, after RD-18 had established + that a reference inside a path to a document that still exists is a pointer, not + provenance, and exempted one. The supervisor did not run that check against `backend/`. + Two such paths existed. The target of 0 gave the agent no way to keep them, so it + described the two documents in prose instead — losing a path that resolved. Fixed + afterwards; the target is 2. **When a ticket repeats an earlier sweep, re-run the earlier + sweep's exemption check against the new scope.** An exemption is a property of the + content, not of the directory that happened to hold it first. + Four habits that prevent all five: - **Use `git grep`, not `grep -r`.** It searches tracked files only, so untracked and