Repository navigation
Context lives beside the code: per-crate READMEs, generated reference, one AGENTS.md (ADR 0078) - #215
Merged
Merged
Conversation
Every statement in the nested AGENTS.md and PLAN.md files, the root session plans and findings, and docs/plans was checked against the code. What no test, ADR or module doc already held moved beside the code it explains: `//!` and `///` docs, test-module docs, and amendments to ADRs 0009, 0015, 0045 and 0049. Open work became issues #199-#202 or was matched to existing ones (#22, #121, #140, #144, #149); `TODO(#200)` and `TODO(#201)` mark the two code sites. Stale claims fixed on the way: - levelset documented grid tangency as an open limitation twice; the SoS fix and a sweeping test already close it. - decimate claimed boundary vertices keep their position; they do not. - boolmesh's `parallel` feature comment claimed a BestEffort determinism drop; it stays Topological. Its struct doc still credited upstream (ADR 0014) after absorption (ADR 0047); `subtract_many`'s doc sat on `cancellation_granularity`; `box_detect` documented checks it does not make; `pair_up` no longer asserts. - mesh-compile's exact path is not extrusion-only, and its chord budget does default to the linear tolerance. - ray-mesh skips, rather than refuses, an out-of-range candidate index. - linear-intersection's closure has four packages, not three. - brep's `finish` had lost its doc to `append`. - ADR 0015's corner-radius follow-up is done (#111). Claude-Session: https://claude.ai/code/session_01V3TnZ5BoKu5PWhZKGXtZuq
Every crate under crates/ and tools/ now has a README.md, and every publishable crate declares `readme = "README.md"` instead of inheriting the workspace README, so crates.io shows each crate's own page. Each README is written for users first: what the crate provides and what it deliberately does not do, `cargo add`, and links to docs.rs and the repository. A short Design notes section appears only where the crate has something no test, ADR or module doc already says. tools/benchmark, tools/oracle, tools/xtask, tests/consumers and native/ get READMEs holding the procedure and inventory their AGENTS.md carried. The axiolid-curve and axiolid-surface descriptions claimed evaluation, composite curves, trimming and swept surfaces; those crates hold values only, and composites, trims and sweeps live in axiolid-model. Both are corrected. boolmesh's `parallel` feature comment claimed a BestEffort determinism drop that does not happen. Claude-Session: https://claude.ai/code/session_01V3TnZ5BoKu5PWhZKGXtZuq
…R 0078) Keep only the root AGENTS.md, rewritten to what a contributor must know before touching the repository: layout, the dependency rule, behaviour rules, where open work lives, and the gate. Delete the other 86 AGENTS.md files, every PLAN.md, docs/plans/, docs/benchmarking-plan.md and the root-level session plans and findings (PLAN-exact-curves*.md, PLAN-geom-layer.md, GAP2-FINDING.md, RTC-FINDING.md); the previous two commits moved what they held that was true and not recorded elsewhere. ADR 0078 records the rule: context lives beside the code, open work lives in issues. The root holds only the manifest, lockfile, toolchain pin, licence, README and AGENTS.md, so the machine-checked declarations move from architecture/ to docs/architecture/, beside the maps generated from them; xtask, the semver and gaps scripts and the docs follow. `cargo xtask context check` enforces it and runs in scripts/gate.sh: - the root AGENTS.md exists, has at most 120 lines and no checkboxes; - no other AGENTS.md or CLAUDE.md, no PLAN*.md, *-plan.md or docs/plans; - no root file outside the allowlist; - every crate under crates/ and tools/ has a README.md of at most 150 lines without checkboxes, and every publishable crate declares it; - a code marker is `TODO(#N)`; bare TODO, FIXME and XXX are rejected; - no pointer at a PLAN.md or nested AGENTS.md, and README pointers resolve. scripts/probe_context_gate.sh mutation-verifies each rule. The roadmap freshness check drops its PLAN.md status rule (kernel#25), which the context check supersedes, and check-docs-ui no longer scans crates/PLAN.md. Claude-Session: https://claude.ai/code/session_01V3TnZ5BoKu5PWhZKGXtZuq
`cargo xtask docs` writes one reference page per publishable crate from its manifest, README and CHANGELOG: description, latest release, crates.io, facade feature, layer, rustdoc on Pages and docs.rs, source, overview and design notes, internal dependencies and the latest changes. It also writes the layer-grouped index that replaces the hand-written docs/reference/crates.md, the sidebar facts the VitePress config reads, the per-crate changelog page (folding in scripts/assemble-crate-changelogs.py, output unchanged but its banner) and the architecture maps. `--check` fails on a stale or orphan page and on a README that lacks its docs.rs, reference-page or source link or makes a publication or version claim; it runs in the gate, with a mutation probe, and in the Pages workflow. Crates only ever released in the workspace-wide 0.3.0 release show that release instead of "not released". The Pages workflow now also builds rustdoc into the site under /api/rustdoc/ and triggers on crate and xtask changes, so a release refreshes the reference without a docs commit. Every publishable README gains its reference-page link. Hand-written pages that duplicated generated content now link to it; getting-started uses `cargo add` and drops a stale claim that crates.io publication was not established. The root README quick start named the facade with no feature, which is a compile error since the default is empty; it now says `cargo add axiolid --features standard`. Claude-Session: https://claude.ai/code/session_01V3TnZ5BoKu5PWhZKGXtZuq
ray-mesh: `nearest_hit_among` skipped a candidate triangle index at or beyond the mesh's triangle count, so a broad phase built over a different mesh answered "no hit" for triangles it never tested. It now refuses with the new `RayMeshError::TriangleIndexOutOfRange`, and `triangle_hit` refuses the same index instead of panicking in the mesh view. `RayMeshError` is exhaustive, so the new variant is breaking: axiolid-ray-mesh goes to 0.4.0, and so does the `axiolid` facade, which re-exports it under `axiolid::ray_mesh`. The C ABI does not expose it. boolmesh: a refusal inside the solve (`pair_up`'s odd edge-point count, #101) was reported as `Degenerate`, which reads as the caller's fault, though the operands had passed every input gate. It is now `BackendContractViolation` naming the provider. tests/solve_failure.rs pins it on a grid union of overlapping unit boxes that still reaches the refusal; that defect is #203. Also: delete a stray tracked nurbs/src/revolution_profile.rs.bak, and regenerate the reference pages for the releases that landed on main. Claude-Session: https://claude.ai/code/session_01V3TnZ5BoKu5PWhZKGXtZuq
GeneralPawz
added a commit
that referenced
this pull request
Sep 29, 2026
Patch release for every publishable crate so crates.io shows each crate's own README.md (ADR 0078, #215), with links to its API documentation, reference page and source. axiolid-ray-mesh 0.4.0 and the axiolid facade 0.4.0 also carry the breaking `RayMeshError::TriangleIndexOutOfRange` refusal; axiolid-mesh-boolean-boolmesh 0.3.2 reports refusals inside the solve as `BackendContractViolation` (#203). Each crate's `[Unreleased]` changelog section is rolled to its version, and the workspace dependency pins follow. Claude-Session: https://claude.ai/code/session_01V3TnZ5BoKu5PWhZKGXtZuq
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Retires the progressive nested
AGENTS.md/PLAN.mdcontext the way openbimrs/ifc did in its PR #179 (ADR 0078). Every crate now has its own README as its crates.io page, and the documentation site's crate reference is generated from the crates themselves.Where the context went (ADR 0078)
AGENTS.md, now the only one (≤120 lines)//!////docs beside that codecargo xtask architecture check, the newcargo xtask context checkREADME.md(≤150 lines)Removed: 86 nested
AGENTS.md, everyPLAN.md,docs/plans/,docs/benchmarking-plan.md, and the root-levelPLAN-*.md/*-FINDING.md. The root now holds only the manifest, lockfile, toolchain pin, licence, README and AGENTS.md.architecture/*.tomlmoves todocs/architecture/.cargo xtask context check(in the gate, mutation-verified byscripts/probe_context_gate.sh) enforces:AGENTS.md/CLAUDE.md;TODO(#N);Generated documentation
cargo xtask docswrites a reference page per crate from its manifest, README and CHANGELOG, plus:scripts/assemble-crate-changelogs.py);--checkruns in the gate (withscripts/probe_docs_gate.sh) and in the Pages workflow. That workflow now also hosts rustdoc under/api/rustdoc/and rebuilds on crate changes. Every README links docs.rs, its reference page and the source, like https://crates.io/crates/ifc-geometry.Stale claims fixed along the way
compile_error!because the default is empty. It now sayscargo add axiolid --features standard.axiolid-curveandaxiolid-surfaceclaimed evaluation.Behaviour changes
nearest_hit_amongrefuses an out-of-range candidate with the newRayMeshError::TriangleIndexOutOfRangeinstead of skipping it.triangle_hitrefuses instead of panicking.RayMeshErroris exhaustive, so the semver gate requires a bump:axiolid-ray-mesh0.4.0, and theaxiolidfacade 0.4.0 because it re-exports it underaxiolid::ray_mesh. The C ABI does not expose it.BackendContractViolation, notDegenerate.tests/solve_failure.rspins it, and the grid-union defect that still reaches it is boolmesh: union of overlapping axis-aligned boxes refuses inside the solve (odd edge-point count) #203.Merging notes
AGENTS.md/PLAN.mdwill conflict with the deletion. Move the edit into its new home when rebasing.axiolid-ray-meshandaxiolidpublish as 0.4.0.Verification
scripts/gate.shpasses. This includes the context and docs checks and their probes, the architecture, closure and gaps checks, build, test, clippy, doc, feature matrix, C ABI, native packaging, the release preflight and semver. The VitePress build with dead-link checking and the docs-ui checks pass as well.https://claude.ai/code/session_01V3TnZ5BoKu5PWhZKGXtZuq