docs: testing map, backlog and contributing after the v1.28/v1.29 releases

- testing.md: nine generators now produce twenty-three artifacts (the
  gen:grammars generator gained arch-highlight.js and gen:example-svgs
  grew to thirteen README SVGs); documents the new roof/void byte-
  identity gate, the fixture-symbol snapshot layer's three
  differently-promised groups, and the v1.29 cross-feature gate that
  neither parallel branch could prove alone.
- CONTRIBUTING.md: mirrors the twenty-three-artifact count and the
  worktree build-refusal / dep-range lockstep guards for the VS Code
  extension.
- backlog.md: 3.11/3.12 marked done (v1.27.0, was already shipped but
  still read FIXED/unreleased); re-measured the spec.llm.md character
  budget (cap raised to 26,000 in v1.29.0, file is 25,636 as of
  2026-08-27, 364 to spare); adds Wave 5 (six items deferred by name in
  v1.28.0/v1.29.0: curved roof offset, polygonal void, void area
  subtraction, glyph-aware mirroring, overhead-dash syntax, angled
  furniture) and re-scopes P2-7 against the widened fixture catalog.
- README.md: furniture-symbol blurb updated to the measured 59
  words / 36 families and the roof/void drawing-only annotations.

All counts re-measured directly against the working tree (fixture
family/category counts, generator/artifact counts, Playwright spec
counts, error/warning catalog counts) rather than carried forward.

Author: ChanMeng666

CONTRIBUTING.md

@@ -146,6 +146,20 @@ diagnostics, or error/lint codes — republish the extension so its bundled serv
 > — run `npm run vscode:build:only && npx vitest run editors/vscode` (CI's `builds` job does exactly
 > this). That replaced the old by-hand "count new keywords in `dist/server.js`" probe.
 
+> **Build and package in the PRIMARY checkout only — the build now refuses otherwise.** A
+> `git worktree` checkout has no `node_modules`, so esbuild resolves the core by walking **up** and
+> bundles the *shared* repo's, and the `__CORE_VERSION__` stamp cannot catch it because both stamp
+> the same version. `editors/vscode/resolve-core.mjs` compares the resolved core's real path against
+> the repo root of the tree being built and throws naming both paths. Junctioning the worktree's
+> `node_modules` does **not** make it safe (npm links a workspace package by absolute path to the
+> main tree), and the guard fires there too — correctly.
+
+> **Its `@chanmeng666/archlang` range is pinned by a test, and every core release turns that test
+> red on purpose.** `editors/vscode/test/lockstep.test.ts` asserts the range is a *string* equal to
+> `^` + the root version; re-pin it as step 2, never relax the check. It is distinct from the
+> freshness stamp above — that one says the BUNDLE is current, this one says the MANIFEST is honest,
+> and the range once sat two releases stale while the stamp stayed green throughout.
+
 A repack can also be **non-language** — the icon, `galleryBanner`, or other marketplace metadata
 (e.g. `0.4.1` was an icon-only repack of `0.4.0`). Same steps 1–4 above (skip step 2 when the core
 did not move); the `.vsix` still needs a manual web upload.
@@ -245,21 +259,22 @@ low.
 
 ### CI drift gates (regenerate before you push)
 
-**Nine generators** produce **twenty-one artifacts**, and CI drift-checks all of them in a single
-`npm run check:drift` step. The authoritative list is the `GENERATORS` table in
-`scripts/check-drift.ts` — this table mirrors it:
+**Nine generators** produce **twenty-three artifacts**, and CI drift-checks all of them in a single
+`npm run check:drift` step. The run prints its own total (`✓ all 23 generated artifacts are in sync
+with their sources`), so read the count there rather than from this page. The authoritative list is
+the `GENERATORS` table in `scripts/check-drift.ts` — this table mirrors it:
 
 | Generated artifact | Generator | Source of truth |
 |--------------------|-----------|-----------------|
-| `editors/archlang.tmLanguage.json`, `playground/src/arch-language.js` | `gen:grammars` | `src/grammar/tokens.ts` |
+| `editors/archlang.tmLanguage.json`, `playground/src/arch-language.js`, `docs-site/.vitepress/theme/arch-highlight.js` | `gen:grammars` | `src/grammar/tokens.ts` |
 | `docs/error-codes.md` | `gen:errors` | `src/error-catalog.ts` |
 | `docs/cli-reference.md` | `gen:cli` | `src/manifest.ts` |
 | `spec.llm.md` | `gen:spec` | `src/grammar/tokens.ts` + `examples/` |
 | `llms-full.txt` | `gen:llms` | `spec.llm.md` + `SKILL.md` + `src/manifest.ts` + `src/error-catalog.ts` |
 | `grammars/archlang.gbnf` | `gen:gbnf` | `src/grammar/tokens.ts` |
 | `schemas/plan.schema.json` | `gen:plan-schema` | `PLAN_JSON_SCHEMA` |
 | `schemas/intent.schema.json` | `gen:intent-schema` | `INTENT_JSON_SCHEMA` |
-| the twelve `examples/*.svg` the README embeds | `gen:example-svgs` | the matching `examples/*.arch` (list: `README_SVGS`) |
+| the thirteen `examples/*.svg` the README embeds | `gen:example-svgs` | the matching `examples/*.arch` (list: `README_SVGS`) |
 
 Whenever a generator's source changes, run `npm run gen:all` to regenerate every artifact in
 dependency order (`gen:spec` before `gen:llms`, which consumes it) and commit the output;

README.md

@@ -250,11 +250,13 @@ fence in your Markdown to images in one step.
 
 Poché-hatched walls (by material), door **swing arcs**, window glazing, computed room areas,
 dimension lines, layers, line weights, a north arrow, a scale bar and a title block. **Real drawn
-symbols for every catalogued furniture kind** — the bathroom and kitchen fixtures, and the room
-furniture beside them, each with the detail that makes it readable at plan scale (see
-[Furniture & Fixtures](docs/furniture.md), or the
-[`furnished-flat`](examples/furnished-flat.arch) example) — plus `dims auto` to synthesize
-dimension strings for you.
+symbols for every catalogued furniture kind** — 59 words across 36 families, the bathroom and
+kitchen fixtures and the room furniture beside them, each with the detail that makes it readable at
+plan scale (see [Furniture & Fixtures](docs/furniture.md), or the
+[`furnished-flat`](examples/furnished-flat.arch) example) — plus the two **drawing-only**
+annotations a plan needs above and below the cut: `roof overhang 600` puts a dashed eaves line
+around the building (an exact mitred offset of the wall ring, at any angle), and `void` puts a stair
+well or an atrium on the floor plate. And `dims auto` synthesizes the dimension strings for you.
 
 </details>
 

docs/backlog.md

@@ -99,7 +99,7 @@ to prevent.
 
 </details>
 
-### 3.11 · `repair(repair(s)) !== repair(s)` — `FIXED` (unreleased)
+### 3.11 · `repair(repair(s)) !== repair(s)` — `done` (v1.27.0)
 
 **`repair` is now idempotent, and it is asserted** — `test/fuzz.test.ts`'s "is idempotent — a second
 call changes nothing", a property over 300 generated plans, plus two named regression specimens in
@@ -147,7 +147,7 @@ Honesty holds throughout: a piece parked mid-cycle gets an `unresolved` entry na
 it alternates between, and a change entry whose net effect is nothing is dropped rather than
 reported. All 27 shipped examples repair byte-identically to before (they are already at a fixpoint).
 
-### 3.12 · `flush` and `grid` fight — `FIXED` (unreleased)
+### 3.12 · `flush` and `grid` fight — `done` (v1.27.0)
 
 A fixture placed `flush` against a 100 mm partition lands on a `…50` coordinate; `grid 100` then
 snapped it back **into** the wall and raised `W_FURNITURE_WALL_COLLISION` on a plan that is correct.
@@ -171,8 +171,13 @@ The agent Skill — the loop a cold-start model follows — documents neither th
 layer nor the four non-default door kinds. `examples/bungalow.arch` now demonstrates both, but
 there is nowhere in `SKILL.md` to reference it from.
 
-Note the constraint before starting: `SKILL.md` feeds `gen:llms`, and `spec.llm.md` sits at
-**24,940 of 25,000 characters** — 60 to spare. Any addition needs its budget worked out first.
+Note the constraint before starting: `SKILL.md` feeds `gen:llms`, and `spec.llm.md` is under a hard
+character cap asserted by `test/llm-spec-drift.test.ts`. **Re-measure both numbers rather than
+trusting this line** — they have moved twice since it was written (the cap was 25,000; v1.29.0
+raised it to **26,000** after trimming a redundant keyword bullet, and the file is **25,636** as of
+2026-08-27, leaving 364). The standing instruction is unchanged and is the point of the cap:
+`spec.llm.md` is injected verbatim into agent prompts, so its size is a recurring per-request token
+cost — **trim duplication before raising.**
 
 ### 3.15 · `W_FURNITURE_WALL_COLLISION` does not check a CURVED wall — `todo`
 
@@ -354,6 +359,69 @@ anywhere. Same "a promise quietly not kept" class as v1.26.1. The fix is to incl
 
 ---
 
+## Wave 5 — deferred by name in v1.28.0 / v1.29.0
+
+Each of these was **named in `CHANGELOG.md` at the time it was skipped**, not quietly omitted, so
+nobody has to guess whether it was overlooked. Two v1.28 entries are already gone from this list:
+`rug`, `sofa_l`, `piano` and `sun_lounger` were deferred there and **shipped in v1.29.0**.
+
+### 5.1 · An `arc` edge under `roof overhang` — `todo`
+
+`roof overhang <mm>` mitres a closed wall ring outward in closed form (line–line intersection,
+orientation from the shoelace sign). A curved edge has no such offset in the same arithmetic, so
+`E_ROOF_CURVED` **refuses** rather than approximating, and the author writes `roof polygon …`
+instead. Same shape as the `arc`-inside-a-`room polygon` deferral below, and probably the same
+design pass: an offset ring that carries arcs is an offset ring whose whole consumer set has to
+learn arcs.
+
+**Gate:** the refusal's own test in `test/roof.test.ts` inverts — an arc-bearing ring must produce
+a drawn eaves line at `R ± overhang` on the curved run, and the exact-coordinate assertions on the
+straight runs must not move.
+
+### 5.2 · A polygonal `void` — `todo`
+
+`void … size WxH` is rectangle-only in v1. A ring form needs the machinery `room polygon` already
+has, and **every consumer here is written on a rectangle**: the nav-grid obstacle, the poly-aware
+room attribution, and `frame.ts`'s `transformElement`. Cheap to add to the grammar, not cheap to
+add to those three.
+
+### 5.3 · Area subtraction under a `void` — `todo`
+
+A void deliberately does **not** reduce its room's area today; `describe --json`'s `voids[]` gives
+the extent so a consumer can subtract. That decision is *pinned* by `test/void.test.ts`, so
+changing it is an argument with a test rather than an oversight — which is the point. Before
+reopening it, decide what a subtracted area means to `schedule rooms`, to the room label's `m²`
+text, and to an intent's area assertion, because those three are what would silently disagree.
+
+### 5.4 · Glyph-aware mirroring in the `place` transform — `todo`
+
+**`sofa_l`'s return is always on the LEFT and there is no right-handed twin.** `place … mirror`
+will not produce one, because a reflection transforms a resolved element's *position* and not the
+symbol drawn inside it — so a mirrored wing draws a left-hand sofa. A `sofa_l_r` category was
+**rejected rather than forgotten**: it would put the fix in the vocabulary, where every future
+handed symbol then needs its own twin. The real fix is for `frame.ts` to hand the glyph its own
+chirality when `det < 0`, which is the same place the handed door/furniture rules already flip.
+
+Note the standing rule it must obey: add a handed rule ⇒ add its flip to `transformElement`, never
+a frame parameter to the element ([ADR 0016](adr/0016-component-instances-and-frames.md)).
+
+### 5.5 · A syntax for overhead dashes — `todo`
+
+`upper_cabinet` is drawn dashed because of *what it is*, and there is no way for an author to say
+"draw this piece above the cut plane" about anything else. Any design has to decide whether it is a
+clause on `furniture`, a property of a category, or a plan-level convention — and a dashed overhead
+line is also what `roof` and `void` now draw, so the three should agree about what dashed *means*
+before a fourth spelling appears.
+
+### 5.6 · Angled furniture — `todo`
+
+A fixture still draws on an **axis-aligned footprint**, so a piece against a sloped wall is not
+turned to it. Deferred by name in v1.28.0. Related but not the same as 3.15 above (which is about
+*measuring* against a curved wall, not drawing at an angle); both are instances of the fixture
+layer knowing only rectangles.
+
+---
+
 ## Wave 4 — P2 language features
 
 Designed and evidenced in `docs/research/2026-08-06-competitor-borrowing-roadmap.md` §5. Each one
@@ -364,7 +432,7 @@ proven by a SHA-256 sweep over the shipped examples), and a corpus entry in the
 
 | # | Feature | Status | Note |
 |---|---|---|---|
-| P2-7 | Four-sided authorable clearances + embedded-insert exemption | `todo` | Most contained — widens `clearanceMm` (`src/fixtures-catalog.ts:21`) to `{front,back,left,right}` plus a per-statement override |
+| P2-7 | Four-sided authorable clearances + embedded-insert exemption | `todo` | Most contained — widens `clearanceMm` (`src/fixtures-catalog.ts:21`) to `{front,back,left,right}` plus a per-statement override. **Re-scope before starting:** v1.28.0 took that catalog from 18 categories to **59 across 36 families** and gave `FixtureSpec` two more flags (`directional`, then v1.29's `underlay`), so "one default per category" is now a far larger table to be right about — and an underlay already has a stated exemption (it never blocks a fixture's use-space) that a four-sided rule must not re-litigate |
 | P2-10 | Feet-and-inches display formatting (`dimension_units standard`) | `todo` | **Display only** — millimetres stay the internal unit and the measured truth. Route through `fmt()` |
 | P2-9 | `outdoor <kind>` + floor-material hatches + auto legend | `todo` | Hatches must be **scale-aware**; do not copy `patternUnits="userSpaceOnUse"` with fixed pixel sizes, which does not scale with drawing scale |
 | P2-8 | Targeted dimension selection (dimensions on named walls/fixtures) | `todo` | Composes with the sheet layer |