Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
AGENTS.md
Use Aetheris.CLI to inspect and validate parts/assemblies during development as ground-truth inspection tool. If
aetherisis not available on PATH, build/run it via dotnet (for exampledotnet run --project Aetheris.CLI -- --helpand corresponding subcommand help) before making assumptions about current capabilities.Update documentation opportunistically during development and surface any inconsistencies or friction immediately; do not defer doc fixes, as the system is evolving rapidly and drift must be corrected in-place.
Follow the repository content-location policy before creating documentation, fixtures, samples, demos, or test-support assets. Current user documentation belongs only under
docs/public/; Firmament-family test source belongs underfixtures/. Generated output must default to ignoredartifacts/local/and followdocs/development/GENERATED-ARTIFACT-POLICY.md. Do not introduce a new top-level content bucket without an explicit architectural reason.
Documentation rules
Read before writing Firmament.
docs/public/learn/anddocs/public/reference/language/describe the language; the compiler (aetheris validate --json) is the final authority.Public docs describe behavior, not milestones. Do not put milestone codes (X0, M2, SURF-X1a), verdicts, test counts or links to development reports in
docs/public. Say what works, what is rejected, and how to use it.Public guide shape. Title; one paragraph on what it is for; a complete, buildable example (prefer linking or quoting a file under
fixtures/); fields and rules; limits ("rejects", "not supported"); links to related guides.Lessons are fixture-backed. Every example in
docs/public/learn/is a file infixtures/Canonical/Learn/listed inPublicDocumentationQualificationTests.LearnLessonExamplesBuildThroughRealCli. Change both together.Work reports go in
docs/development/reports/<yyyy-mm>/, short: what changed, evidence, verdict. Not indocs/release/, which holds release notes and package readmes only.History. When an era of reports closes, summarize it in
docs/development/history/eras/, add lasting decisions tohistory/DECISIONS.md, list the originals inhistory/ORIGINALS.md, and delete them (git keeps them). Before deleting any doc,git grepits file name outside Markdown: tests, scripts and module descriptors read some docs by path.Experimental work (humanoid, garments, reconstruction) is documented under
docs/public/experimental/with an experimental banner, never presented as product.Aetheris introduce utility scoring as a first class concept within its JudgmentEngine to use when appropriate.
- When a subsystem must select among multiple bounded strategies, prefer JudgmentEngine so admissibility, scoring, tie-breaking, and rejection reasons are explicit.
- Do not use JudgmentEngine for simple deterministic transformations, ordinary enum dispatch, null checks, or reductions where no competing interpretation exists.
Convergence rule
Every substantial task must end in exactly one of three states:
Success
The intended capability works in the real path and the real motivating case materially improves.Meaningful progression
The capability is not complete, but one genuine blocker is removed and the next blocker is isolated with evidence.Honest stop
Further work would require overbroad scope expansion, excessive debt, brittle patching, or tangled logic. Stop and report the reason with concrete evidence.
Do not continue producing patches once the work stops converging.
Do not confuse activity with progress. A failed attempt is only acceptable if it leaves behind a narrower problem, stronger evidence, or a justified stop.
Any partial work must leave the codebase in a cleaner, more legible, and more diagnosable state than before.
Test execution requirement
Do not skip .NET build/test validation just because dotnet is missing from the current environment.
If the required .NET SDK/runtime is not installed:
- detect that explicitly,
- install the required .NET version for this repo,
- verify
dotnetis available on PATH, - then run the full build/test commands.
Do not report .NET tests as “not run due to missing dotnet” unless installation is impossible in the current environment, and if so, explain exactly why.
Test lanes
Iterate with the fast lane and gate on the full one:
dotnet test Aetheris.Kernel.Core.Tests -c Release --no-build --filter "Category!=SlowCorpus"
dotnet test Aetheris.slnx -c Release --no-build
The full lane runs test projects in parallel; that is the day-to-day gate. Never report a change as verified on the fast lane alone - it omits the corpus-driven tests, which are the ones that catch interchange regressions.
CI runs the parallel lane on every push and pull request; release qualification runs the serial one.
The serial lane is an optional determinism check, not a daily gate. Run it when a change touches shared static state (caches, memos, ambient context), test isolation, or ordering, or when a parallel-lane failure looks order-dependent:
dotnet test Aetheris.slnx -c Release --no-build -m:1 -- RunConfiguration.MaxCpuCount=1
When a test needs a STEP corpus file, take it from Step242Corpus (Body, Import or Text)
rather than reading and importing it again. See CONTRIBUTING.md for when a test genuinely needs
its own import.