c454a3af10
* feat(skill): replace skill-pack with per-harness conditional compiler
skillbuild compiles the skill tree into per-target harness builds:
- <!-- skill:if omp,!claude --> blocks include text only for matching
targets; name-list conditions only, no else/nesting, fail-loud on
unknown targets and unpaired/nested directives
- fence-aware: directive-looking lines inside code fences are literal
- layout is the filesystem; tree root configured in skillproj.toml
- post-build assertion: zero directive residue, SKILL.md frontmatter
name check
Migration to the new model:
- docs/skill/ becomes the self-contained source root (SKILL.md,
references/, generated api/stdlib/core/guides now under
references/docs/; SDK_OVERVIEW/LICENSE/inspect are ordinary tree
files)
- auto_docs_gen output redirected into the tree (docs/api ->
docs/skill/references/docs/api, likewise stdlib)
- skills/simplecadapi/ is now the compiled omp target output;
dist/generic/simplecadapi the generic target
- dropped skill-pack entry point (plus dangling evolve/make-export
entries and their orphaned test), release workflow builds via
skillbuild + tar; README updated
First real conditional block: harness reading paths in SKILL.md
(skill:// mount on omp vs disk-relative on generic).
Verified: 59 tests pass (skillbuild 31, auto_docs_gen 19, persistence
regression 9); both targets build; outputs residue-clean; full suite
collects (1376 tests).
* refactor(tools): auto_docs_gen moves out of the installed package
tools/ scripts are repo-checkout dev scripts, not packaged CLIs:
- auto_docs_gen.py now lives in tools/ beside the other generators;
auto_tools/ package removed entirely
- path resolution simplifies: repo root = parent of tools/, fail-loud
if pyproject.toml missing; site-packages/cwd fallback branches were
dead code once the script stopped shipping in the wheel
- auto-docs-gen console script dropped from [project.scripts];
release.yml and README invoke python tools/auto_docs_gen.py
- MANIFEST.in stale src/auto_tools include removed; CadQuery-free
runtime scan no longer needs the auto_tools filter
- run_examples.py retired (user removal): README example-runner text
updated to direct examples/ scripts; dangling runner-contract test
(runpy.run_path into the deleted script) removed
Verified: 53 tests pass (auto_docs_gen + skill_build + ocp runtime
scan) and test_example_model_contract passes; regeneration from
tools/ is byte-identical (zero docs drift).
* refactor(skill): strip harness and build-tool content from the skill tree
The skill is plain harness-neutral content again:
- SKILL.md 'Reading skill files' section removed (the omp skill://
mount block and its !omp complement were the only conditional
blocks; the tree compiles identically for every target now)
- references/README.md: build-tool meta removed ('per-harness
conditional compilation', skillbuild packaging/validation claims —
link validation was never implemented, so the claim was false)
- live test now asserts the tree stays harness-neutral (zero blocks)
- skillproj.toml targets aligned with the user's output table
(omp -> skills/simplecadapi-omp, opencode -> skills/simplecadapi-opencode;
leftover 'generic' entry had no output and failed the build)
- compiled outputs are regenerable artifacts: skills/simplecadapi/
untracked from git, skills/simplecadapi-*/ gitignored, release.yml
and README build via skillbuild and tar the omp output directly
(bsdtar has no --transform; inner dir keeps its suffixed name)
Verified: 49 tests pass; both targets build 372 files with zero
conditional blocks; no omp/conditional/directive residue in the tree
or outputs.
* chore(docs): drop stale architecture review and design notes
4.0 KiB
4.0 KiB
Discipline: Feature Ordering
Operation order is a robustness recommendation, not an SDK-enforced canonical sequence. Put fragile steps late when that improves diagnosis and repair.
Evidence labels
- SDK contract: documented operation results and failure behavior.
- Modeling guidance: recommended source organization; other valid operation orders remain possible when the resulting inputs are valid.
Recommended first-pass order
base solid
→ major additive features
→ subtractive features (openings, pockets)
→ shell
→ through-wall holes
→ fillets and chamfers last
Why: fillets are often failure-prone, and boolean/detail operations may change the topology used by later selections. Postponing fragile details often keeps the model easier to repair; it is not a mandatory SDK ordering rule.
Boolean tool geometry
- Modeling guidance: overshoot through-cut tools. Extend cutting tools past
the faces they enter and exit. The amount is part-scale and design-dependent;
1 mmis not an SDK default or guarantee. Coincident or coplanar tool/target faces are a common kernel failure mode. - Modeling guidance: combine identical repeated cuts when convenient; validate one representative before patterning.
union_rsolidhas a one-manifold-Solidresult contract and fails when it cannot produce one. Face-area contact or positive-volume overlap can work; edge-, vertex-, and tangent-only contact cannot satisfy that contract.cut_rsolid(..., skip_non_intersecting=False)makes non-intersecting tools fail instead of being silently skipped. Treat this as a strict diagnostic mode; whether a skipped tool is acceptable is a workflow decision.
Selecting what to fillet
- Radius must fit the local geometry: when a profile cannot accept the
nominal radius, reduce it, narrow the edge selection, or move the operation
later. This SDK's fillet fails explicitly (
ValueError: Fillet failed) — there is no silent radius fallback, so treat any failure as a signal to change radius, selection, or order. - Filter selected edges by feature intent; split edge groups by feature rather than filleting everything at once.
- Prefer robust selections (tags, axes, normals, positions, QL predicates) over topology indexes; booleans and fillets renumber topology.
Patterns
- Verify equal spacing/angles on at least two units before patterning
(
linear_pattern_rsolidlist,radial_pattern_rsolidlist); repetition is a hypothesis until measured. - Pattern after the prototype feature validates; never pattern an unvalidated feature to hide a defect.
Structure the source to localize failure
Each feature is a named step — a per-feature function or a distinct intermediate variable — so a failed operation names one feature, and a parameter change touches one obvious place. Print a small QL-derived fact after each major step (counts, centers, volume) so drift is caught at the step that caused it.
Complex surfaces
loft_rsolidacceptsWire/Vertexsections and the implementation enables OCCT compatibility checking. Modeling guidance: keep corresponding wire sections topologically compatible (same edge count and meaningful feature boundaries). Compatibility checking is not a substitute for authoring corresponding sections or validating the resulting solid.- When authoring wires from sampled data, sample along common rails so each section places the same feature at the same edge. Cluster samples toward feature lines or regions where curvature changes fastest.
- Interpolation choice matters: a curve that is flat at each control point (zero derivative at both ends of every interval) can put a crease at every knot; measurement noise in control curves can become visible surface ripple. Smooth control data before lofting through it.
- Use
track_section_contours_rdescriptorevidence when section topology changes across stations (birth/death/split/merge); do not force a topology-changing sequence into one global loft.