From fbc1418cd5c404a61032b4148867ac6e2962ee2f Mon Sep 17 00:00:00 2001 From: Rahul Tomar Date: Fri, 6 Nov 2026 21:57:38 +0100 Subject: [PATCH] Fresh-start check; README says what works and what doesn't yet Step 3 of the plan to 0.1.0. The repository was cloned into an empty folder and Getting started followed as written: tools, PDK, services, .env from the example, the API, the web app (WebAssembly built on first start), a starter project to "Ready for expert review", and the tests. No step was missing or wrong. The record is in docs/release-rehearsal.md. The README gets a "What works, and what doesn't yet" section. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 +++ README.md | 27 +++++++++++++++++++++++++++ docs/release-rehearsal.md | 20 ++++++++++++++++++++ 3 files changed, 50 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f1b71b9..92f151d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,9 @@ All notable changes to Wafersmith are recorded here. The format follows ### Added +- **What works, and what doesn't yet** in the README, and the fresh-start check in the + [release rehearsal](docs/release-rehearsal.md): a clean clone runs by following Getting started + with no step missing. - **Release rehearsal** ([docs/release-rehearsal.md](docs/release-rehearsal.md)): the counter, UART receiver and FIFO starters taken to a clean layout in the browser, timed, with no code typed and no AI: 1 to 4 minutes each, every case tried and every planted mistake caught. diff --git a/README.md b/README.md index 80a88dd..fe29fc7 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,33 @@ which started the project and leads its development. | **AI agent** | Proposes changes that can only be merged when the simulation gate passes, with an evidence log. | | **IP registry** | Publish blocks, import them pinned to a commit, with licence compatibility checks. | +## What works, and what doesn't yet + +**Works today**, checked end to end in the [release rehearsal](docs/release-rehearsal.md): + +- Small designs (counters, a UART, a FIFO, a debouncer and the like) from the start page to a + layout that passes DRC, LVS and timing on IHP SG13G2, without typing Verilog or testbench code. +- Examples as tests, coverage of every branch, planted mistakes, and searches that find the + examples still missing. A failing example can be explained value by value ("why is it this + value?", "why wasn't it the expected one?") and often repaired by a small fix, all without AI. +- Two people editing the same project live; Git history for everything. +- Running it all on one machine, from a clean clone, by following + [Getting started](docs/getting-started.md). + +**Not yet**, or only partly: + +- **Larger designs.** Everything has been tested at starter size (up to a few hundred cells). + The simulator covers the synthesisable Verilog these designs use plus functions, tasks and + generate blocks, not all of Verilog or SystemVerilog. +- **What only an expert can sign off**: I/O pads and pin placement, manufacturing test (scan), + behaviour at power-up, timing with real gate delays in simulation, analog parts, and the final + go/no-go for a real chip run. Health says so on every project. +- **AI features need a key and cost money.** Describing a change in words, the assistant and the + agent use Claude (or OpenRouter) and count against a daily budget; without a key they are off and + everything else works. Their quality is measured by the [design evals](docs/evals.md). +- **Tested on one setup**: Linux on aarch64, with Docker. Other platforms should work but have + not been checked. + ## Quick start (local development) You need Rust, Node 22 with pnpm, and Docker. Full instructions, including the WebAssembly diff --git a/docs/release-rehearsal.md b/docs/release-rehearsal.md index b011149..59a1772 100644 --- a/docs/release-rehearsal.md +++ b/docs/release-rehearsal.md @@ -53,6 +53,26 @@ it is checkable without knowing Verilog. pane that was hidden, where the page's per-frame updates don't run. A page someone is looking at updates at once. +## Fresh-start check + +Step 3 of the plan, on 6 Nov 2026: the repository cloned into an empty folder and +[Getting started](getting-started.md) followed as written, with nothing else. + +| Step | Result | +| --- | --- | +| Prerequisites (Rust, Node 22 with pnpm, Docker, the wasm target, wasm-bindgen 0.2.130) | all present at the versions named | +| `./scripts/fetch-verible.sh` | Verible installed into `.tools/verible/` | +| `./scripts/fetch-pdk.sh` | PDK enabled in the `wafersmith_pdk` volume (image already pulled) | +| `docker compose ... up -d` | Postgres and Rauthy running | +| `cp .env.example .env` and `cargo run -p wafer-api` | built and listening on 8090 with the example settings unchanged; the AI off, as described, without a key | +| `pnpm install && pnpm dev:web` | the WebAssembly built on first start; the app served | +| Sign in, a project from the LED blinker starter, examples, planted mistakes, build | "Ready for expert review" | +| `cargo test --workspace` and the web typecheck | all pass | + +No step was missing or wrong, so the guide is unchanged. Not checked: pulling the 7.5 GB +LibreLane image over the network (it was already present), and a machine without Rust or Node +installed. + ## Not covered - **A change made with the AI.** The starters were used as they come; changing a design in words