#331 - Audit: laws & design-spec conformance across the codebase — findings documented as comments on this ticket - crueber/walhub

crueber commented

2026-09-11 15:43:44 +00:00

Owner

What's requested

A complete audit of how well the repo's design specs and laws have been followed, with every deviation found documented as a comment on this ticket — one comment per finding, so each can be discussed, ruled on, and resolved independently.

This is a research/audit ticket: the deliverable is comments on this issue, not code changes.

The audit's terms of reference

What counts as "the laws and design":

AGENTS.md §1 — the numbered laws (dependency budget, git-as-subprocess, concurrency/lock order, and the rest of the numbered list).
AGENTS.md §2 — the operational rules (spec spelling, test identity pinning, fresh-clone compile, CI publishing, etc.).
docs/go/*.md (01–17) — the normative architecture specs; each doc's "Decisions & deviations" section is part of the record.
docs/features/*.md (01–11) — the feature specs, each with their own wire/store/layout contracts and cache-class rules.
DEVIATIONS.md — the already-ratified deviation ledger (a finding that's already ratified there is a non-finding; cite it and move on).

Audit method (per area, evidence required):

Dependency budget (law 1): diff go.mod require list and web/package.json runtime deps against the law's exact allowlist. Any undeclared dev-time tool counts too.
Git-as-subprocess (law 2): grep for any git library import; sample internal/git argv construction against docs/go/04_git.md's specified argv.
Concurrency (law 3): every concurrent design must carry a ### Concurrency subsection; check lock order syncMu → packMu → rw usage and TryLock-only rw writes against docs/go/13_concurrency.md.
Wire/store contract conformance: spot-check handlers against their spec rows in docs/go/07_api.md (cache classes per §4 — the two-class rule, []-not-null, RFC 3339, plain-text errors, three route twins per NonRepo route, RegisterExposed coverage) and store keys against docs/go/02_storage_protobuf.md.
Feature-spec conformance: for each docs/features/*.md, verify the landed implementation matches the spec's endpoint table, auth classes, and storage keys — the known OpenUI-scan found several (#71–#98 audit wave) but nothing systematic since.
Docs vs reality: normative docs claiming behavior the code doesn't have (the #76 class), and code shipping behavior no doc describes (the law-12 amendment duty).
Frontend laws: npm allowlist, no TypeScript, Solid-signals-only state, Tailwind v4 CSS-first, headless-module rule (web/src/lib/ importable in Node), the node --test glob rule.
Spec-spelling and naming keepers: fmtSpecSize/fmtSpecDuration render rules, §9 naming/compat identity changes in DEVIATIONS.md.

Deliverable format (each finding = one comment):

Title line: the law/spec section violated + one-line summary.
Evidence: file:line (or diff) showing the deviation.
Severity: law violation (rejected-change class) vs spec drift (doc amendment needed) vs docs-lie (doc fix needed).
Recommendation: fix the code, amend the spec, or ratify into DEVIATIONS.md.
Known deviations already in DEVIATIONS.md (D-WEB-6, D-WEB-7, 17.1, the R1 rulings) are cited as context, not re-filed.

Known hot spots to prioritize (from this ticket-tracker's own history): the cache-class drift family (#280 — ccSWR copy-pasted across feature packages, spec'd in two feature docs), discovery/RegisterExposed coverage gaps (#272 — most feature packages never registered), and anything the audit waves #71–#98 touched that may have regressed.

Scope guards

No code changes. The audit ends with findings documented; fixes become their own tickets afterward (by the user's ruling per finding).
Findings must be reproducible from the current main — cite the commit SHA the audit ran against.
Not a style review: only laws, spec conformance, and docs-vs-reality are in scope.

Acceptance criteria

Every law in AGENTS.md §1 audited against the code, with a pass/fail comment (pass = short comment citing what was checked; fail = full finding format).
Every docs/go/ and docs/features/ spec checked for docs-vs-reality drift in its core contracts (endpoint tables, storage keys, cache classes, auth classes).
go.mod and web/package.json diffed against law 1 exactly.
Each finding is a separate comment with evidence, severity, and recommendation; the comment set is cross-linked from a summary comment (count of findings by severity + audit commit SHA).
DEVIATIONS.md-ratified items are cited as non-findings, not re-reported.

## What's requested A **complete audit of how well the repo's design specs and laws have been followed**, with every deviation found documented as a **comment on this ticket** — one comment per finding, so each can be discussed, ruled on, and resolved independently. This is a research/audit ticket: the deliverable is comments on this issue, not code changes. ## The audit's terms of reference **What counts as "the laws and design":** - `AGENTS.md` §1 — the numbered laws (dependency budget, git-as-subprocess, concurrency/lock order, and the rest of the numbered list). - `AGENTS.md` §2 — the operational rules (spec spelling, test identity pinning, fresh-clone compile, CI publishing, etc.). - `docs/go/*.md` (01–17) — the normative architecture specs; each doc's "Decisions & deviations" section is part of the record. - `docs/features/*.md` (01–11) — the feature specs, each with their own wire/store/layout contracts and cache-class rules. - `DEVIATIONS.md` — the already-ratified deviation ledger (a finding that's already ratified there is a **non-finding**; cite it and move on). **Audit method (per area, evidence required):** 1. **Dependency budget (law 1):** diff `go.mod` require list and `web/package.json` runtime deps against the law's exact allowlist. Any undeclared dev-time tool counts too. 2. **Git-as-subprocess (law 2):** grep for any git library import; sample `internal/git` argv construction against `docs/go/04_git.md`'s specified argv. 3. **Concurrency (law 3):** every concurrent design must carry a `### Concurrency` subsection; check lock order `syncMu → packMu → rw` usage and TryLock-only `rw` writes against `docs/go/13_concurrency.md`. 4. **Wire/store contract conformance:** spot-check handlers against their spec rows in `docs/go/07_api.md` (cache classes per §4 — the two-class rule, `[]`-not-null, RFC 3339, plain-text errors, three route twins per NonRepo route, `RegisterExposed` coverage) and store keys against `docs/go/02_storage_protobuf.md`. 5. **Feature-spec conformance:** for each `docs/features/*.md`, verify the landed implementation matches the spec's endpoint table, auth classes, and storage keys — the known OpenUI-scan found several (`#71–#98` audit wave) but nothing systematic since. 6. **Docs vs reality:** normative docs claiming behavior the code doesn't have (the #76 class), and code shipping behavior no doc describes (the law-12 amendment duty). 7. **Frontend laws:** npm allowlist, no TypeScript, Solid-signals-only state, Tailwind v4 CSS-first, headless-module rule (`web/src/lib/` importable in Node), the `node --test` glob rule. 8. **Spec-spelling and naming keepers:** `fmtSpecSize`/`fmtSpecDuration` render rules, §9 naming/compat identity changes in `DEVIATIONS.md`. **Deliverable format (each finding = one comment):** - **Title line**: the law/spec section violated + one-line summary. - **Evidence**: file:line (or diff) showing the deviation. - **Severity**: law violation (rejected-change class) vs spec drift (doc amendment needed) vs docs-lie (doc fix needed). - **Recommendation**: fix the code, amend the spec, or ratify into `DEVIATIONS.md`. - Known deviations already in `DEVIATIONS.md` (D-WEB-6, D-WEB-7, 17.1, the R1 rulings) are cited as context, not re-filed. **Known hot spots to prioritize** (from this ticket-tracker's own history): the cache-class drift family (#280 — `ccSWR` copy-pasted across feature packages, spec'd in two feature docs), discovery/`RegisterExposed` coverage gaps (#272 — most feature packages never registered), and anything the audit waves #71–#98 touched that may have regressed. ## Scope guards - No code changes. The audit ends with findings documented; fixes become their own tickets afterward (by the user's ruling per finding). - Findings must be reproducible from the current `main` — cite the commit SHA the audit ran against. - Not a style review: only laws, spec conformance, and docs-vs-reality are in scope. ## Acceptance criteria - [ ] Every law in `AGENTS.md` §1 audited against the code, with a pass/fail comment (pass = short comment citing what was checked; fail = full finding format). - [ ] Every `docs/go/` and `docs/features/` spec checked for docs-vs-reality drift in its core contracts (endpoint tables, storage keys, cache classes, auth classes). - [ ] `go.mod` and `web/package.json` diffed against law 1 exactly. - [ ] Each finding is a separate comment with evidence, severity, and recommendation; the comment set is cross-linked from a summary comment (count of findings by severity + audit commit SHA). - [ ] `DEVIATIONS.md`-ratified items are cited as non-findings, not re-reported.

crueber added the

git storage

label

2026-09-11 15:43:44 +00:00

crueber added this to the v1 milestone

2026-09-11 15:43:44 +00:00

crueber commented

2026-09-11 17:21:31 +00:00

Author

Owner

[FINDING — docs-lie, law 12] DEVIATIONS.md D-DEP-1 still claims 'exactly three modules', contradicting the ratified x/crypto fourth module

Evidence (audit commit 70d29dd):

DEVIATIONS.md:17 — D-DEP-1 'Backend budget: exactly three modules', Status: in force (file last updated 2026-09-01).
go.mod — 4 direct requires: BurntSushi/toml v1.6.0, go-chi/chi/v5 v5.3.2, golang.org/x/crypto v0.56.0, golang.org/x/net v0.58.0.
AGENTS.md law 1 already amended 2026-09-02 (x/crypto for SSH transport only); docs/go/17_ssh.md:156-160 records decision 17.1 amending Law 1.

Severity: docs-lie (doc fix needed, not a code violation — the code matches the amended law).
Recommendation: amend D-DEP-1 in DEVIATIONS.md to the four-module budget in the same change as any touch of that section; cite 17.1.

**[FINDING — docs-lie, law 12] DEVIATIONS.md D-DEP-1 still claims 'exactly three modules', contradicting the ratified x/crypto fourth module** Evidence (audit commit 70d29dd): - DEVIATIONS.md:17 — D-DEP-1 'Backend budget: exactly three modules', Status: in force (file last updated 2026-09-01). - go.mod — 4 direct requires: BurntSushi/toml v1.6.0, go-chi/chi/v5 v5.3.2, golang.org/x/crypto v0.56.0, golang.org/x/net v0.58.0. - AGENTS.md law 1 already amended 2026-09-02 (x/crypto for SSH transport only); docs/go/17_ssh.md:156-160 records decision 17.1 amending Law 1. Severity: docs-lie (doc fix needed, not a code violation — the code matches the amended law). Recommendation: amend D-DEP-1 in DEVIATIONS.md to the four-module budget in the same change as any touch of that section; cite 17.1.

crueber commented

2026-09-11 17:21:35 +00:00

Author

Owner

[FINDING — docs-lie, law 12] DEVIATIONS.md D-DEP-2 still claims 'zero npm runtime dependencies', contradicting ratified D-WEB-6/D-WEB-7

Evidence (audit commit 70d29dd):

DEVIATIONS.md:18 — D-DEP-2 'Frontend budget: zero npm runtime dependencies; one devDependency (esbuild)', Status: in force.
web/package.json dependencies: solid-js, @solidjs/router, marked@18.0.11, dompurify@3.4.15 (exactly the AGENTS.md law-1 allowlist as amended 2026-09-02 D-WEB-6 and 2026-09-06 D-WEB-7); devDependencies add vite, vite-plugin-solid, tailwindcss, @tailwindcss/vite alongside esbuild.
D-WEB-6 (DEVIATIONS.md:28) and D-WEB-7 (:29) are recorded in the same file as in force, so the file contradicts itself.

Severity: docs-lie (code matches the amended law; the ledger is stale).
Recommendation: mark D-DEP-2 superseded-by-chain (D-WEB-6 → D-WEB-7) instead of in force.

**[FINDING — docs-lie, law 12] DEVIATIONS.md D-DEP-2 still claims 'zero npm runtime dependencies', contradicting ratified D-WEB-6/D-WEB-7** Evidence (audit commit 70d29dd): - DEVIATIONS.md:18 — D-DEP-2 'Frontend budget: zero npm runtime dependencies; one devDependency (esbuild)', Status: in force. - web/package.json dependencies: solid-js, @solidjs/router, marked@18.0.11, dompurify@3.4.15 (exactly the AGENTS.md law-1 allowlist as amended 2026-09-02 D-WEB-6 and 2026-09-06 D-WEB-7); devDependencies add vite, vite-plugin-solid, tailwindcss, @tailwindcss/vite alongside esbuild. - D-WEB-6 (DEVIATIONS.md:28) and D-WEB-7 (:29) are recorded in the same file as in force, so the file contradicts itself. Severity: docs-lie (code matches the amended law; the ledger is stale). Recommendation: mark D-DEP-2 superseded-by-chain (D-WEB-6 → D-WEB-7) instead of in force.

crueber commented

2026-09-11 17:21:41 +00:00

Author

Owner

[FINDING — docs-lie, law 12] DEVIATIONS.md D-PKG-2 ('node stage exists ONLY to run esbuild') contradicts the ratified vite build

Evidence (audit commit 70d29dd):

DEVIATIONS.md:87 — D-PKG-2 'a node stage exists ONLY to run esbuild (pnpm run build:sdk)', Status: in force, 'supersedes Node-20 web stage, twice'.
Dockerfile:8-19 — web stage is node:22-alpine + pnpm@11.25.0 running 'pnpm run build' = build:ui (vite SolidJS+Tailwind SPA into dist/) AND build:sdk (esbuild), per web/package.json scripts and Makefile:11 ('vite then esbuild').
D-WEB-6 (same file) reinstated the full node/vite web build by explicit user request.

Severity: docs-lie (Dockerfile + Makefile match D-WEB-6; the ledger entry is stale).
Recommendation: amend D-PKG-2 to describe the vite+esbuild node stage (or mark superseded by D-WEB-6). Could be folded with the D-DEP-1/D-DEP-2 ledger-refresh into one 'DEVIATIONS.md staleness pass' ticket.

**[FINDING — docs-lie, law 12] DEVIATIONS.md D-PKG-2 ('node stage exists ONLY to run esbuild') contradicts the ratified vite build** Evidence (audit commit 70d29dd): - DEVIATIONS.md:87 — D-PKG-2 'a node stage exists ONLY to run esbuild (pnpm run build:sdk)', Status: in force, 'supersedes Node-20 web stage, twice'. - Dockerfile:8-19 — web stage is node:22-alpine + pnpm@11.25.0 running 'pnpm run build' = build:ui (vite SolidJS+Tailwind SPA into dist/) AND build:sdk (esbuild), per web/package.json scripts and Makefile:11 ('vite then esbuild'). - D-WEB-6 (same file) reinstated the full node/vite web build by explicit user request. Severity: docs-lie (Dockerfile + Makefile match D-WEB-6; the ledger entry is stale). Recommendation: amend D-PKG-2 to describe the vite+esbuild node stage (or mark superseded by D-WEB-6). Could be folded with the D-DEP-1/D-DEP-2 ledger-refresh into one 'DEVIATIONS.md staleness pass' ticket.

crueber commented

2026-09-11 17:21:45 +00:00

Author

Owner

[FINDING — law violation (law 6 mechanism absent) + docs-lie, law 12] The sim tier is specified but does not exist: internal/sim/ absent, 'make sim' is a no-op

Evidence (audit commit 70d29dd):

AGENTS.md law 6: happy-path budgets 'are asserted in the sim (docs/go/15_testing.md)'; §2 working rules: 'make sim when you touched internal/wal'.
docs/go/15_testing.md:180-206 normatively specifies internal/sim scenarios TestSim_SafetyThenLiveness, TestSim_HealthyRequestRoundTripBudgets (push ≤6 ops, warm refs ≤1, cold refs ≤2, checkpoint ≤4, counted via FaultStore link Stats.Ops), TestSim_LivenessUnderRandomSeeds; §4.8 presents the budgets as asserted. No 'not yet implemented' note anywhere in the doc.
Reality: internal/ has NO sim package (api, bundle, checks, config, devtools, e2e, egress, events, git, identity, issues, maintain, mirror, notify, policy, pulls, releases, repoimport, review, server, sizecatalog, social, sshd, store, tags, wal — no sim). FaultStore exists (internal/store/fault/fault.go:105 Ops counter), but nothing consumes it for budgets.
Makefile:76 lists sim in .PHONY but defines NO sim recipe: 'make -n sim' → 'Nothing to be done for sim'. Only push has a budget test (cmd/walhub/push_budget_test.go:174 TestPushFastPathZeroCollabRoundTrips); warm/cold-refs and checkpoint budgets are asserted nowhere.

Severity: law violation class (the assertion mechanism law 6 mandates is absent) + docs-lie (doc 15 presents the tier as normative/landed).
Recommendation: either land internal/sim per doc 15 §4, or record an explicit decision (doc 15 Decisions section + DEVIATIONS.md) deferring/descoping it and fix AGENTS.md law 6 + §2 + Makefile references to match reality.

**[FINDING — law violation (law 6 mechanism absent) + docs-lie, law 12] The sim tier is specified but does not exist: internal/sim/ absent, 'make sim' is a no-op** Evidence (audit commit 70d29dd): - AGENTS.md law 6: happy-path budgets 'are asserted in the sim (docs/go/15_testing.md)'; §2 working rules: 'make sim when you touched internal/wal'. - docs/go/15_testing.md:180-206 normatively specifies internal/sim scenarios TestSim_SafetyThenLiveness, TestSim_HealthyRequestRoundTripBudgets (push ≤6 ops, warm refs ≤1, cold refs ≤2, checkpoint ≤4, counted via FaultStore link Stats.Ops), TestSim_LivenessUnderRandomSeeds; §4.8 presents the budgets as asserted. No 'not yet implemented' note anywhere in the doc. - Reality: internal/ has NO sim package (api, bundle, checks, config, devtools, e2e, egress, events, git, identity, issues, maintain, mirror, notify, policy, pulls, releases, repoimport, review, server, sizecatalog, social, sshd, store, tags, wal — no sim). FaultStore exists (internal/store/fault/fault.go:105 Ops counter), but nothing consumes it for budgets. - Makefile:76 lists sim in .PHONY but defines NO sim recipe: 'make -n sim' → 'Nothing to be done for sim'. Only push has a budget test (cmd/walhub/push_budget_test.go:174 TestPushFastPathZeroCollabRoundTrips); warm/cold-refs and checkpoint budgets are asserted nowhere. Severity: law violation class (the assertion mechanism law 6 mandates is absent) + docs-lie (doc 15 presents the tier as normative/landed). Recommendation: either land internal/sim per doc 15 §4, or record an explicit decision (doc 15 Decisions section + DEVIATIONS.md) deferring/descoping it and fix AGENTS.md law 6 + §2 + Makefile references to match reality.

crueber commented

2026-09-11 17:21:49 +00:00

Author

Owner

[FINDING — spec drift (minor), law 12] Doc 15 D3 names Make targets with no recipe: test-slow, contract-fs, dev (plus sim, filed separately)

Evidence (audit commit 70d29dd):

docs/go/15_testing.md D3 lists as Make targets: build, fmt, vet, test, race, cover, test-slow, sim, contract, contract-fs, contract-s3, contract-gcs, e2e, image, dev, dev-store, dev-store-stop, clean, ci.
Makefile recipes (grep '^[a-z-]*:'): web, build, fmt, vet, test, test-go, test-web, race, cover, contract, contract-s3, contract-gcs, landing-gifs, e2e, image, dev-store, dev-store-stop, clean, ci, help. Missing: test-slow, contract-fs, dev (and sim — no recipe, only .PHONY).
'make test-slow' / 'make contract-fs' / 'make dev' → 'No rule to make target'. (contract-fs is subsumed by 'contract' running memory+filesystem per Makefile:43; test-slow/dev simply don't exist.)

Severity: spec drift, minor (doc over-claims; no code behavior at stake).
Recommendation: amend D3's target list to the actual Makefile (or restore the missing targets). Fold into the same ticket as the sim finding if the sim lands.

**[FINDING — spec drift (minor), law 12] Doc 15 D3 names Make targets with no recipe: test-slow, contract-fs, dev (plus sim, filed separately)** Evidence (audit commit 70d29dd): - docs/go/15_testing.md D3 lists as Make targets: build, fmt, vet, test, race, cover, test-slow, sim, contract, contract-fs, contract-s3, contract-gcs, e2e, image, dev, dev-store, dev-store-stop, clean, ci. - Makefile recipes (grep '^[a-z-]*:'): web, build, fmt, vet, test, test-go, test-web, race, cover, contract, contract-s3, contract-gcs, landing-gifs, e2e, image, dev-store, dev-store-stop, clean, ci, help. Missing: test-slow, contract-fs, dev (and sim — no recipe, only .PHONY). - 'make test-slow' / 'make contract-fs' / 'make dev' → 'No rule to make target'. (contract-fs is subsumed by 'contract' running memory+filesystem per Makefile:43; test-slow/dev simply don't exist.) Severity: spec drift, minor (doc over-claims; no code behavior at stake). Recommendation: amend D3's target list to the actual Makefile (or restore the missing targets). Fold into the same ticket as the sim finding if the sim lands.

crueber commented

2026-09-11 17:21:52 +00:00

Author

Owner

[FINDING — spec drift (minor), law 12] ssh-keys NonRepo routes lack /api-browser/v1 twins required by the 07 §3 lane note

Evidence (audit commit 70d29dd):

docs/go/07_api.md lane note (~L109-111): 'Non-repo endpoints have /api/v1 and /api-browser/v1 twins, plus /services/api/… twins for owners/instance.'
internal/api/routes.go:42-44: GET/POST /api/v1/ssh-keys and DELETE /api/v1/ssh-keys/{fp} have NO /api-browser/v1 twin (only GET /api-browser/v1/me exists at :45). Every other NonRepo route in the table (:46-64) carries full twins.
Mitigating context: docs/go/17_ssh.md:89 and docs/go/11_config_cli.md:66 name only 'GET|POST|DELETE /api/v1/ssh-keys', and the UI uses the token lane directly (web/src/pages/Keys.jsx:23,43,68 fetch '/api/v1/ssh-keys' same-origin). So this is a doc-clarity gap, not a functional bug.

Severity: spec drift, minor.
Recommendation: amend the 07 §3 lane note to carve out self-service ssh-keys as token-lane-only (or add the twins + ExposedTemplates). Suggest ruling alongside any 17_ssh.md touch.

**[FINDING — spec drift (minor), law 12] ssh-keys NonRepo routes lack /api-browser/v1 twins required by the 07 §3 lane note** Evidence (audit commit 70d29dd): - docs/go/07_api.md lane note (~L109-111): 'Non-repo endpoints have /api/v1 and /api-browser/v1 twins, plus /services/api/… twins for owners/instance.' - internal/api/routes.go:42-44: GET/POST /api/v1/ssh-keys and DELETE /api/v1/ssh-keys/{fp} have NO /api-browser/v1 twin (only GET /api-browser/v1/me exists at :45). Every other NonRepo route in the table (:46-64) carries full twins. - Mitigating context: docs/go/17_ssh.md:89 and docs/go/11_config_cli.md:66 name only 'GET|POST|DELETE /api/v1/ssh-keys', and the UI uses the token lane directly (web/src/pages/Keys.jsx:23,43,68 fetch '/api/v1/ssh-keys' same-origin). So this is a doc-clarity gap, not a functional bug. Severity: spec drift, minor. Recommendation: amend the 07 §3 lane note to carve out self-service ssh-keys as token-lane-only (or add the twins + ExposedTemplates). Suggest ruling alongside any 17_ssh.md touch.

crueber commented

2026-09-11 17:21:56 +00:00

Author

Owner

[PASS — law 1] Dependency budget: go.mod and web/package.json match the amended allowlist exactly

Checked at 70d29dd: go.mod requires exactly BurntSushi/toml v1.6.0, go-chi/chi/v5 v5.3.2, x/crypto v0.56.0, x/net v0.58.0 (+ indirect x/sys, x/text) — the 4 allowed backend modules (chi core only; no chi/cors, chi/middleware, x/sync — C-1 honored, hand-rolled errgroup in internal/store/errgroup.go). web/package.json runtime deps exactly solid-js + @solidjs/router + marked@18.0.11 + dompurify@3.4.15; dev tools vite + vite-plugin-solid + tailwindcss + @tailwindcss/vite + esbuild only. No other package.json files carry deps. (The DEVIATIONS.md ledger lagging these amendments is filed as separate findings; the code and AGENTS.md are consistent.)

**[PASS — law 1] Dependency budget: go.mod and web/package.json match the amended allowlist exactly** Checked at 70d29dd: go.mod requires exactly BurntSushi/toml v1.6.0, go-chi/chi/v5 v5.3.2, x/crypto v0.56.0, x/net v0.58.0 (+ indirect x/sys, x/text) — the 4 allowed backend modules (chi core only; no chi/cors, chi/middleware, x/sync — C-1 honored, hand-rolled errgroup in internal/store/errgroup.go). web/package.json runtime deps exactly solid-js + @solidjs/router + marked@18.0.11 + dompurify@3.4.15; dev tools vite + vite-plugin-solid + tailwindcss + @tailwindcss/vite + esbuild only. No other package.json files carry deps. (The DEVIATIONS.md ledger lagging these amendments is filed as separate findings; the code and AGENTS.md are consistent.)

crueber commented

2026-09-11 17:21:58 +00:00

Author

Owner

[PASS — law 2] Git-as-subprocess: no git library imports; sampled argv matches docs/go/04_git.md

Checked at 70d29dd: grep for go-git/git2go/libgit2/src-d bindings across *.go → zero hits. Sampled argv: internal/git/refs.go:494 + bundle.go:343 'update-ref --stdin' (04 §4.3 grammar), refs.go:808 persistent 'cat-file --batch' peel cache (04 §D-ENG-4), upload.go:58 '-c uploadpack.allowSidebandAll=true upload-pack' (04:492). D-ENG-2 rev-list/cat-file-check pipeline and D-ENG-6 git.binary plumbing noted in code comments.

**[PASS — law 2] Git-as-subprocess: no git library imports; sampled argv matches docs/go/04_git.md** Checked at 70d29dd: grep for go-git/git2go/libgit2/src-d bindings across *.go → zero hits. Sampled argv: internal/git/refs.go:494 + bundle.go:343 'update-ref --stdin' (04 §4.3 grammar), refs.go:808 persistent 'cat-file --batch' peel cache (04 §D-ENG-4), upload.go:58 '-c uploadpack.allowSidebandAll=true upload-pack' (04:492). D-ENG-2 rev-list/cat-file-check pipeline and D-ENG-6 git.binary plumbing noted in code comments.

crueber commented

2026-09-11 17:22:01 +00:00

Author

Owner

[PASS — law 3] Concurrency: subsections present in every docs/go spec; TryLock-only rw writes honored

Checked at 70d29dd: every docs/go/01-17 doc carries Concurrency subsections (### in 02/04/07/08/12/13/14/16/17, #### in 01/03/05/06/09/10, numbered §§ in 11/15). Code: rw writes go only through TryWriteLock (internal/wal/reconcile.go:317, eviction.go:178-182); no blocking rw.Lock( anywhere; RLock readers at handle.go:305 are the sanctioned long-held read guards. Canonical primitive internal/wal/rw.TryRWMutex per ruling C-2; lock order syncMu → packMu → rw documented at handle.go:3. No out-of-order acquisition found in sampled paths.

**[PASS — law 3] Concurrency: subsections present in every docs/go spec; TryLock-only rw writes honored** Checked at 70d29dd: every docs/go/01-17 doc carries Concurrency subsections (### in 02/04/07/08/12/13/14/16/17, #### in 01/03/05/06/09/10, numbered §§ in 11/15). Code: rw writes go only through TryWriteLock (internal/wal/reconcile.go:317, eviction.go:178-182); no blocking rw.Lock( anywhere; RLock readers at handle.go:305 are the sanctioned long-held read guards. Canonical primitive internal/wal/rw.TryRWMutex per ruling C-2; lock order syncMu → packMu → rw documented at handle.go:3. No out-of-order acquisition found in sampled paths.

crueber commented

2026-09-11 17:22:05 +00:00

Author

Owner

[PASS — hot spots] Cache-class drift (#280) and RegisterExposed coverage (#272) show no regression

Checked at 70d29dd: all feature packages define the spec'd classes — pulls/issues/social/identity/releases use 'private, no-cache' mutable-collab + version/folded ETags with 304 paths, 'no-store' on lists/task starts, SWR kept only where spec'd (pulls diff at pulls/http.go:571 per 03 §8; ref-dependent core routes). review/checks/tags/mirror/repoimport/notify literal no-store matches their specs (04/05: all no-store). Every feature package (issues, pulls, review, checks, social, releases, notify, identity, mirror, repoimport, tags) declares ExposedTemplates AND is composed via api.RegisterExposed in cmd/walhub/*.go in the same change (law 12 honored in code comments); discovery derives endpoints[] from the live route table + registry (internal/api/discovery.go:26-46, D-API-2 phantom-route rule intact).

**[PASS — hot spots] Cache-class drift (#280) and RegisterExposed coverage (#272) show no regression** Checked at 70d29dd: all feature packages define the spec'd classes — pulls/issues/social/identity/releases use 'private, no-cache' mutable-collab + version/folded ETags with 304 paths, 'no-store' on lists/task starts, SWR kept only where spec'd (pulls diff at pulls/http.go:571 per 03 §8; ref-dependent core routes). review/checks/tags/mirror/repoimport/notify literal no-store matches their specs (04/05: all no-store). Every feature package (issues, pulls, review, checks, social, releases, notify, identity, mirror, repoimport, tags) declares ExposedTemplates AND is composed via api.RegisterExposed in cmd/walhub/*.go in the same change (law 12 honored in code comments); discovery derives endpoints[] from the live route table + registry (internal/api/discovery.go:26-46, D-API-2 phantom-route rule intact).

crueber commented

2026-09-11 17:22:11 +00:00

Author

Owner

[PASS — sampled] Feature endpoint tables, storage keys, wire rules, and laws 4/5/7/8/9/10/11 spot checks

Checked at 70d29dd: 01 identity dispatch (routeUsers/routeOrgs/routeInvites, self-or-admin PUT, owner-gated rosters) matches the §8 table; 02/03 keys use the spec'd num:06x hex-storage/decimal-wire idiom with pr.json + mergeable.json sidecars; 04 review dispatch covers the reviews/threads/requests/suggest table; 10 import + 11 mirror dispatch (incl. both lanes, method matrix, 404/409/503 shapes, scrubbed errors) match their tables; 12_runner freeze honored (doc is DRAFT 'no code may land', no runner/actions code exists). Wire: plain-text errors via writePlain, RFC 3339 consts, []-initialized lists, per-segment decoding + both lanes everywhere. Laws: no upward imports from store/wal/git (law 8); golden proto fixtures in internal/store/proto/testdata/golden (law 5); task single-flight present (wal/singleflight.go — law 7); oidc-requires-allowlist enforced in config/validate.go:110 (law 9); setup-only 503 mode present in internal/server (law 10); cover gate ≥95 configured (Makefile:34-41) with samples policy 97.4% / config 95.7% (law 11). Frontend: zero .ts/.tsx, Tailwind v4 CSS-first (ui.css @import tailwindcss), render-md.js marked+DOMPurify wrapper (D-WEB-7), node --test uses glob in Makefile:29 + Woodpecker:32, pnpm allowBuilds + dist/.keep per field lessons.

**[PASS — sampled] Feature endpoint tables, storage keys, wire rules, and laws 4/5/7/8/9/10/11 spot checks** Checked at 70d29dd: 01 identity dispatch (routeUsers/routeOrgs/routeInvites, self-or-admin PUT, owner-gated rosters) matches the §8 table; 02/03 keys use the spec'd <num:06x> hex-storage/decimal-wire idiom with pr.json + mergeable.json sidecars; 04 review dispatch covers the reviews/threads/requests/suggest table; 10 import + 11 mirror dispatch (incl. both lanes, method matrix, 404/409/503 shapes, scrubbed errors) match their tables; 12_runner freeze honored (doc is DRAFT 'no code may land', no runner/actions code exists). Wire: plain-text errors via writePlain, RFC 3339 consts, []-initialized lists, per-segment decoding + both lanes everywhere. Laws: no upward imports from store/wal/git (law 8); golden proto fixtures in internal/store/proto/testdata/golden (law 5); task single-flight present (wal/singleflight.go — law 7); oidc-requires-allowlist enforced in config/validate.go:110 (law 9); setup-only 503 mode present in internal/server (law 10); cover gate ≥95 configured (Makefile:34-41) with samples policy 97.4% / config 95.7% (law 11). Frontend: zero .ts/.tsx, Tailwind v4 CSS-first (ui.css @import tailwindcss), render-md.js marked+DOMPurify wrapper (D-WEB-7), node --test uses glob in Makefile:29 + Woodpecker:32, pnpm allowBuilds + dist/.keep per field lessons.

crueber commented

2026-09-11 17:22:16 +00:00

Author

Owner

[AUDIT SUMMARY] Laws & design-spec conformance audit — 6 findings, 5 passes (commit 70d29ddc33, main, read-only, zero code changes)

Findings by severity:

Law-violation class: 1 — sim tier absent + 'make sim' no-op (law 6 mechanism + law 12).
Docs-lie (doc fix needed): 3 — DEVIATIONS.md D-DEP-1 (x/crypto), D-DEP-2 (zero-npm), D-PKG-2 (esbuild-only node stage) all stale vs ratified amendments.
Spec drift (minor): 2 — doc-15 D3 Make-target list (test-slow, contract-fs, dev); ssh-keys missing api-browser twins vs 07 §3 lane note.
Non-findings cited and moved on: D-WEB-6/D-WEB-7, 17.1, R1 rulings C-1..C-4.

Passes: law 1 budget · law 2 git-subprocess · law 3 concurrency · #280/#272 hot spots · feature tables/keys/wire + laws 4/5/7/8/9/10/11 samples.

NOT verified (reason): full per-route auth-class matrix — sampled only, needs handler-by-handler pass; law 4 push-ACK-before-bucket-ACK ordering — needs publish-path trace; full ≥95% cover gate — 2 packages sampled, full 'make cover' not run (time); features 05/06/07/08 tables in full — cache/auth lines sampled; anything browser-rendered — no browser per instructions (curl/CDP explicitly out of scope for this ticket); MASTER_RUST_SPEC.md byte-compat beyond golden fixtures — fixtures + codec review only.

**[AUDIT SUMMARY] Laws & design-spec conformance audit — 6 findings, 5 passes (commit 70d29ddc3363e0905ecf13b328764da72d4d7df7, main, read-only, zero code changes)** Findings by severity: - Law-violation class: 1 — sim tier absent + 'make sim' no-op (law 6 mechanism + law 12). - Docs-lie (doc fix needed): 3 — DEVIATIONS.md D-DEP-1 (x/crypto), D-DEP-2 (zero-npm), D-PKG-2 (esbuild-only node stage) all stale vs ratified amendments. - Spec drift (minor): 2 — doc-15 D3 Make-target list (test-slow, contract-fs, dev); ssh-keys missing api-browser twins vs 07 §3 lane note. - Non-findings cited and moved on: D-WEB-6/D-WEB-7, 17.1, R1 rulings C-1..C-4. Passes: law 1 budget · law 2 git-subprocess · law 3 concurrency · #280/#272 hot spots · feature tables/keys/wire + laws 4/5/7/8/9/10/11 samples. NOT verified (reason): full per-route auth-class matrix — sampled only, needs handler-by-handler pass; law 4 push-ACK-before-bucket-ACK ordering — needs publish-path trace; full ≥95% cover gate — 2 packages sampled, full 'make cover' not run (time); features 05/06/07/08 tables in full — cache/auth lines sampled; anything browser-rendered — no browser per instructions (curl/CDP explicitly out of scope for this ticket); MASTER_RUST_SPEC.md byte-compat beyond golden fixtures — fixtures + codec review only.

crueber referenced this issue

2026-09-11 17:22:38 +00:00

DEVIATIONS.md staleness pass: D-DEP-1, D-DEP-2, D-PKG-2 contradict ratified amendments #337

crueber referenced this issue

2026-09-11 17:22:38 +00:00

Sim tier specified but missing: no internal/sim, make sim is a no-op, budgets unasserted #338

crueber referenced this issue

2026-09-11 17:22:38 +00:00

ssh-keys NonRepo routes lack /api-browser/v1 twins required by 07 §3 lane note #339

crueber commented

2026-09-11 17:22:42 +00:00

Author

Owner

Audit findings converted to child issues: #337 (DEVIATIONS.md staleness: D-DEP-1/D-DEP-2/D-PKG-2), #338 (missing sim tier + Makefile targets), #339 (ssh-keys lane twins). This ticket closes once all three children are closed.