* 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
Discipline: Geometric Validation
Deterministic checks decide pass/fail; scale them to the specification. Every user-specified dimension requires a targeted measurement.
Evidence labels
- SDK contract:
Solid.get_volume()returns a volume measurement;simplecadapi.inspect.brepexposes diagnostic reports such asvalid, volume, and shell closure for BREP outside aGraphSession. - Validation guidance: the combination of checks below is a recommended
gate, not a single SDK
Solid.is_valid()method.
Validity is not positive volume
Validity and positive volume answer different questions. Volume is meaningful per solid, not only after aggregating multiple bodies; a positive and a negative body can cancel in an aggregate and hide the problem.
After boolean/detail operations, check the gates relevant to the artifact:
Solid.get_volume() > 0 for positive material volume, plus BREP diagnostics
from simplecadapi.inspect.brep (inspect_shape_rbrepinspection or
inspect_step_rbrepinspection) when validity and shell closure matter. These
inspection functions run outside GraphSession; they are diagnostic APIs, not
graph operations. Solid has no public is_valid() method.
A boolean can also leave a body that is geometrically right but topologically invalid — correct bounds and volume, one bad face — which survives until the next operation fails far from the cause. Gate every boolean result, not just the final one.
Incremental grounding
Every major step prints a small QL-derived fact: selected face count, a center, an edge count, volume, bounding box. Print only the facts that validate the current step — never whole solids or full model objects. This is what makes drift catchable at the step that caused it instead of at final review.
Selection discipline
- Select by tags, axes, normals, positions, or QL predicates — not arbitrary topology indexes, which booleans and fillets renumber.
- Indexed getters (
get_faces(index),get_edges(index), ...) are for intentional picks; they are preserved as graph geo-select nodes. apply_tag(shape=..., tag=...)attaches a tag to exactly the given shape with LOCAL scope — it never propagates downward;list_tags(shape=...)reads effective tags. Downward/topology-scoped propagation is only exposed byapply_tag_rselectionwith an explicit propagation policy. Keep numeric facts in metadata, never in tags.- A QL-selected face or edge reused by a later feature is preserved as a stable geo-select node in replayable graphs.
Replay as a gate
When a flow claims replayability, prove it: export_model_json(session=...)
→ replay_model_json(json_str=...) in a fresh process, and check the
replayed output count/values. A replay that was never run is a claim, not a
check.
Spec-driven measurement
Every dimension, clearance, offset, and relationship in the brief gets a targeted check:
- Distances and thicknesses: bounded measurements on selected geometry.
- Flush/centered interfaces: measured deltas, not visual impression.
- Patterns: at least two units measured for spacing/angle before trusting the pattern.
- Assemblies: solve residuals, coaxiality of mated axes, flush faces, repeated
occurrences at named positions (
assembly-positioning.md).
Visual review converts to deterministic checks
A visual concern found at review (misplaced feature, wrong silhouette) is not
closed by "looks better now": convert it into a deterministic geometry check
that would have caught it, then run that check. Rendering and comparison
renders (render_step_comparison_rpath) are evidence for review — visual
similarity never replaces strict comparison where the contract requires it.
Report only what ran
State the checks that actually executed, with their outcomes. An intended
check that was not run is reported as not run — implying success without
running a check is the cardinal reporting failure. Structural safety, fatigue,
thermal, vibration, tolerance compliance, and regulatory fitness are never
claimed from geometry alone (manufacturing-boundaries.md).