# 08 — Gaps, open questions and honest tensions --- ## 1. The enforcement gap — a day's work that changes what the site can claim There is **no linter, no formatter and no type-checker anywhere in the estate.** Ordered by value: | # | Fix | Effort | |---|---|---| | **F1** | **Delete `[^_]` from `test_no_legacy_imports.py`** — the guard has never worked; 228 real imports across 69 files | 4 characters | | **F2** | **A `ruff` config** encoding: no docstrings, ban `pydantic` / `Literal` / direct `boto3`, empty `__init__.py` | one config block | | **F3** | **Import alignment** — the 39% number, and the only formatting rule that is measurably inconsistent | a formatter rule or a `tests/ci` check | | **F4** | **`shellcheck` on rendered `Section__*` output** — the generated shell is currently unlintable because it is never rendered outside production | a test | | **F5** | **`eslint`** — 4-space, single quotes, no semicolons, plus a check that every component directory has all three of `.js`/`.html`/`.css` | half a day | | **F6** | **`stylelint`** — the highest-value CSS rule is **no literal colours outside the token file** | an hour | | **F7** | **A banner check** — present, well-formed, three content lines | ~20 lines | | **F8** | **Filename == class name, one class per file** | ~20 lines | F1 and F4 are the two that would catch real defects today. F2, F6 and F7 are close to free. --- ## 2. Build-fresh items | # | Item | Why | |---|---|---| | **G1** | **Rules for JS, CSS, HTML and Bash** | All 31 documented rules are Python and process. The other four languages have consistent, discoverable conventions and **zero written rules** | | **G2** | **A human-readable style guide** | The rules live in `.claude/CLAUDE.md`, an agent instruction file. There is no published standard anywhere. **This is the site** | | **G3** | **The `/for-agents/` argument** | `05__` §5. Named nowhere, and the thing that explains why the rest looks the way it does | | **G4** | **A worked "add a new spec" walkthrough** | The generalisation mechanisms are real (`manifest.py`, route loader, CLI builder). Nobody has written the tutorial that uses them | | **G5** | **A worked "add a new component" walkthrough** | Same for the JS triplet + CDN pattern | | **G6** | **Golden rendered shell files** | Commit one per `Section__*` so a reviewer sees the actual shell, not the template | | **G7** | **A decision record format** | Rules 14, 15 and 21 are scar tissue with the precedent cited inline. That is an ADR in all but name — give it a shape | --- ## 3. Open questions | # | Question | Where it stands | |---|---|---| | **Q1** | **Is alignment for humans or for machines?** `05__` §3 makes the machine-readability argument. It is a claim, not an established fact, and it is falsifiable | The honest page says: it costs diff noise, it buys scanability, here is why we think the trade is worth it in a codebase 61% written by an agent | | **Q2** | **Is rule 9 (no `_private`) Python-only?** | 97 Python violations; universal in JS. **The document does not say, so in practice it is neither enforced nor retired** | | **Q3** | **Which token prefix?** `--bg-panel`, `--sg-surface`, `--sgl-tab-h` — three families for one system | Pick one, or document what each means. The numbered ramps (`--text-1..4`, `--sg-sp-1..4`) are the good part and should be kept either way | | **Q4** | **Should a public coding standard document a `dev.` host?** | Every component example imports from `dev.tools.sgraph.ai`. Redacting it teaches nothing; publishing it documents a `dev.`-prefixed contract as canonical. `07__` §4 | | **Q5** | **Does runtime type safety replace static analysis, or defer it?** | `Type_Safe` catches shape errors at construction. It does not catch unreachable code, unused imports, shadowed names or a typo in a branch never executed. **The honest answer is that it replaces one kind of checking and the other kind is simply absent** | | **Q6** | **Is "no mocks, no patches" affordable outside this estate?** | It works here — 4,785 tests in 81 seconds — because `Type_Safe` objects are cheap and there is an in-memory composition path. Whether it generalises is a real question and the site should not assume it does | | **Q7** | **Does the no-build-step position survive the next dependency?** | 50 files, one level of imports, no CJS-only package yet. `02__` §5 names where it stops working | --- ## 4. Honest tensions 1. **31 written rules and zero enforcement.** High compliance on most of them — 100%, 99.7%, 99% — achieved by discipline rather than tooling. That is impressive and it is fragile, and the one guard that was supposed to hold a line **had never worked**. 2. **A style guide for five languages that documents one.** Python has 31 rules. JavaScript, CSS, HTML and Bash have consistent conventions and no rules at all — which means they are currently maintained by whoever last read the neighbouring file. 3. **Alignment is either the best or the worst convention here.** No formatter in the industry will produce it, so adopting it means never adopting `black`, `prettier` or `gofmt`-style tooling. That is a real, permanent cost accepted for a benefit that has not been measured. 4. **The rules were written for agents and are published to none.** `.claude/CLAUDE.md` is read by every session and by no human who has not gone looking for it. 5. **Runtime validation is a good fit for generated code and a poor substitute for a linter.** Both are true, and the estate currently has the first and not the second. 6. **The most interesting page is the least verifiable.** `/for-agents/` is the original contribution, and its central claim — that these conventions suit a model reader — is asserted from design intent and commit statistics, not from measurement. **Publish it as a position with the evidence attached, not as a finding.** --- ## 5. Loose ends worth an hour each - **Confirm whether a second theme file exists.** The token names suggest dark-first; this pack could not verify a light theme. - **Count how many components exist outside the sg-compute tree.** The CDN serves `base`, `tokens`, `vault-client`, `vault-write` — is there a wider registry? - **Check whether `SgComponent`'s source is public.** Every example imports it; if it is not readable, the pattern cannot be adopted by anyone outside. - **Resolve the `sp-cli:` event namespace** — 23 files, legacy naming, and renaming it breaks external listeners. - **Decide the semicolon rule** and reformat `shared/` to match `components/`. - **Write down the `set -euo pipefail` rule** — 2 of 5 files, three different forms, no rule. - **Extract the four `tests/ci/` guards into a reusable module.** They are the pattern the `/enforce/` page recommends, and they currently live only in one repo. --- This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).