LinkML guardrails: GENERATED banners, regen-no-diff CI, schema-adherence test#13
Merged
Conversation
…, adherence test Makes Principle I (LinkML = source of truth, DEC-57) enforceable rather than aspirational — the three deferred ADR-0011/0012 follow-ups: - GENERATED banners on every derived artefact (generate.sh stamps remit.ts / remit.schema.json / index.html) + .gitattributes linguist-generated. - regen-no-diff CI (schema-regen.yml): regenerates from the schema and fails on any schema/gen + site/data-model drift; toolchain pinned (linkml / linkml-runtime==1.11.1, Python 3.11), byte-reproducible. - schema-adherence test (test/schema-adherence.test.mjs, ajv dev-only): validates a committed Orbat + a kernel Plan against the generated JSON Schema; wired into a new unit.yml CI job (the unit suite never ran in CI before — only e2e + typecheck did). The adherence guard immediately surfaced the full extent of the documented Waypoint hex/square drift (Asset.position, Stamp.start, Materialisation.trajectory) plus appetites map-vs-list and TideDecision (bugs.md) — stripped and tracked via the test's DRIFT map; the Waypoint->HexCell migration is the surfaced follow-up. ajv added as a dev-only dependency (ADR-0014-approved, test-only — never imported by app/ or the kernel). 32 unit tests (+2) green; 0 typecheck errors. ADR-0029. https://claude.ai/code/session_01EhtBoKXg6bHnKdquacyknf
Contributor
|
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
2 participants
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.
Makes Principle I (LinkML is the one source of truth, DEC-57) enforceable rather than aspirational — the three deferred guardrails logged in ADR-0011/0012. (The fourth note — migrating the app's inline shapes onto the generated TS — stays its own spec.)
The three guardrails
schema/generate.shstamps@generated — DO NOT EDITon every derived file (a//block onremit.ts, a$commentfirst-key onremit.schema.json— textual insert, no reformat churn — and an HTML comment onindex.html), plus.gitattributesmarking themlinguist-generated.schema-regen.yml)schema/gen/+site/data-model/, so the committed artefacts can't silently fall out of step withschema/*.yaml. Toolchain pinned (linkml/linkml-runtime==1.11.1, Python 3.11) and verified byte-reproducible (idempotent, empty diff).test/schema-adherence.test.mjs)Orbat(red/green/own-force) and a kernelPlan(Stamp/Scores/Materialisation) — and validates them against the generated JSON Schema with ajv (draft-2019-09).The adherence guard earned its keep immediately
Validating real instances surfaced that the documented
Waypointsquare-vs-hex drift (bugs.md) is broader thanSteeringDelta— it also hitsAsset.position,Stamp.start,Materialisation.trajectory— and flagged two more: the kernel carriesappetitesas a{axis:setting}map where the schema modelsAppetite[], andTideDecisionshapes differently.These pre-existing drifts are stripped per class (the test's
DRIFTmap) before strict validation, so the guard is green yet still fails on any new drift (proven by an undeclared-field assertion). Each is recorded inbugs.md; the Waypoint→HexCell migration + appetites/tide reconciliation (then emptyingDRIFT) is the concrete next follow-up this guard makes visible — deliberately not done here to keep this a pure guardrail, not a schema migration.Notes for review
test:unit— golden fixtures, ORBAT, routing) had never run in CI; only e2e + typecheck did. Addedunit.ymlso the adherence guard (and all the others) actually fire on PRs.ajvadded dev-only — test-only, never imported byapp/or the kernel. No runtime dependency.app/or kernel code changed.Recorded as ADR-0029; drifts in
bugs.md;key_facts.md+ work-log updated.https://claude.ai/code/session_01EhtBoKXg6bHnKdquacyknf
Generated by Claude Code