From 2d09005bc85a29bbb1726e14324490bb21c22080 Mon Sep 17 00:00:00 2001 From: Francois Lanusse Date: Fri, 21 Aug 2026 10:57:21 +0200 Subject: [PATCH] Docs rewrite 5/5: reconcile CLAUDE.md and the doc-drift check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The freeze is over, so the rules that enforced it go: CLAUDE.md now says docs are live and every change lands with its docs — the verb's cli/ page, the module's api/ page, the user guide for visible behavior — with the same document-only-what-exists discipline. The design-doc pointer records the decision made during the rewrite: the records stay in the sibling checkout and are dropped when the rebuild completes, never imported. The workflow inventory catches up too (run-eval label, check-docs, release-tracking deploys), as does the extending table's docs column. check-docs.yml gets a prompt that knows the new structure: a map from change kind to doc home, and the two failure modes that matter most — quoted console output drifting from what the CLI prints, and docs describing anything the code no longer delivers. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01DJzmp2MUhwiNHR94cB91dx --- .github/workflows/check-docs.yml | 26 +++++++++++++++++++++----- CLAUDE.md | 31 ++++++++++++++++++++----------- 2 files changed, 41 insertions(+), 16 deletions(-) diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml index a8d68c73..fe9d23eb 100644 --- a/.github/workflows/check-docs.yml +++ b/.github/workflows/check-docs.yml @@ -34,14 +34,30 @@ jobs: Your task: check whether the project documentation is still accurate and complete given the code changes introduced by this PR. + The documentation is structured, and each kind of change has a home: + - A verb's flags, output, JSON shape, or exit codes → its page in docs/cli/ + (one page per verb, plus the overview's exit-code contract). + - An engine module's responsibility, key symbols, or invariants → its page + in docs/api/ (hand-written module tours) and, for cross-cutting shifts, + docs/architecture.md. + - User-visible behavior (scaffold contents, states, refusal messages, + environment model, SLURM, publication) → docs/user/ (getting-started + quotes real console output; troubleshooting quotes real refusals) and + README.md's quick start. + - Test structure, dev workflow, or conventions → docs/contributing/. + Steps to follow: 1. Run: git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }} to get the list of changed files. - 2. Read the changed source files (focus on .py, .ts, .js, .go, .rs files). - 3. Read existing documentation files (README*, docs/**/*.md, CHANGELOG*, CONTRIBUTING*). - 4. SKIP any files under skills/ or named SKILL.md — these are not user-facing docs. - 5. Identify any documentation that is now inaccurate, incomplete, or missing - given the code changes. + 2. Read the changed source files (focus on src/**/*.py and the workflows). + 3. Read the documentation pages the map above points at for those changes. + 4. SKIP CLAUDE.md and evals/ — agent instructions and the eval harness are + maintained separately, not user-facing docs. + 5. Identify documentation that is now inaccurate, incomplete, or missing. + Two failure modes matter most here: a quoted console output or refusal + message that no longer matches what the CLI prints, and a documented + flag, verb, state, or file that no longer exists (the docs must never + describe more than the code delivers — no foreshadowing). Then: - Post a comment on PR #${{ github.event.pull_request.number }} summarising diff --git a/CLAUDE.md b/CLAUDE.md index f160e694..bea1b08f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,8 +34,10 @@ spec: > spec, the decisions win. It lives in the sibling checkout for now > (branch `redesign_prototype`), alongside its decision records > (rationale, substrate tradeoffs, hermeticity enforcement, the v6 -> review); it moves into this repo's `docs/design/` when the docs are -> rewritten at the end of the rebuild. +> review). It stays in the sibling checkout and is **dropped when the +> rebuild completes** (decision, 2026-08): the design records are not +> imported into this repo's docs — the rewritten `docs/` carries the +> current design, and this file carries the decisions. The pre-rebuild codebase (Snakemake shim, authored Containerfiles, `container:` in `astra.yaml`, vendored dask executor plugin, WRROC export) @@ -104,10 +106,15 @@ Each of these has been asked for in review at least once; none is optional. - **No dead code.** If nothing in the current layer calls it, it doesn't land yet. `lc --help` advertises only verbs that work. -- **`docs/` is frozen at its pre-rebuild state, by decision.** It still - describes the old Snakemake architecture and the full command set. - Don't patch it layer by layer — it gets rewritten in one pass once the - rebuild is complete. Same for `README.md` and `zensical.toml`. +- **`docs/` is live again** (rewritten 2026-08, PRs #185–#188; the + freeze is over). The site is two tracks — user guide + developer + corner — and a change now lands with its docs: a new or changed verb + updates its `docs/cli/` page, an engine change updates its + `docs/api/` module page, and user-visible behavior updates the user + guide. The docs' own rules match this file's: document only what + exists, quote refusals from real runs, and verify every command + block by executing it. `check-docs.yml` reviews each merged PR for + drift. - **Port with intent.** Prior implementations (this repo's git history, and the `redesign_prototype` branch of the sibling `lightcone-cli` checkout) are references, not sources of truth. Neither is the spec by @@ -201,10 +208,12 @@ uv build # wheel + sdist (CI runs this only to publish) Test, lint and type-check are the whole loop, and they are what `.github/workflows/{tests,lint}.yml` run. There is deliberately no task runner in between — the pre-rebuild `justfile` was 90 lines of wrappers -around them plus recipes for the frozen docs and the dormant eval. The -other workflows are `eval.yml` (the agentic eval, on dispatch or any -non-draft PR — flipping a draft to ready triggers it), -`pypi-publish.yaml`, and `docs-deploy.yml` for the frozen docs. +around them. The docs build with `uv sync --group docs && uv run +zensical build`. The other workflows are `eval.yml` (the agentic eval, +on dispatch or the `run-eval` PR label; re-trigger by re-adding the +label), `check-docs.yml` (doc-drift review on merged PRs), +`pypi-publish.yaml`, and `docs-deploy.yml` (deploys on release, so the +site tracks the released CLI). ## Key Invariants (layer 1) @@ -2172,7 +2181,7 @@ unlinks before writing; a new tampering test should too. | To... | Read | Key patterns | |---|---|---| -| Add the next layer | the spec (§11 = the layer ordering) | Land code + tests + deps together; update the layer table above. Docs are deliberately deferred | +| Add the next layer | the spec (§11 = the layer ordering) | Land code + tests + deps together; update the layer table above and the docs pages the layer touches | | Change what a scaffolded file contains | `src/lightcone/engine/templates/files/` | Edit the `.tmpl`; add new ones to `TEMPLATE_NAMES`, and a renderer only if the file needs a substituted value or a merge policy | | Add a value to the scaffold | `src/lightcone/engine/templates/__init__.py` | Derive it from the environment or our own metadata before introducing a constant | | Change what gets converged | `src/lightcone/engine/project.py` + `tests/test_project.py` | `_Converger.item` / `.file`; repairs only ever append |