docs(contributing): define script graduation doctrine and binding vocabulary#711
Merged
graphite-app[bot] merged 1 commit intoJun 9, 2026
Conversation
Contributor
Author
How to use the Graphite Merge QueueAdd either label to this PR to merge it via the merge queue:
You must have a Graphite account in order to use the merge queue. Sign up using this link. An organization admin has enabled the Graphite Merge Queue in this repository. Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue. This stack of pull requests is managed by Graphite. Learn more about stacking. |
This was referenced Jun 9, 2026
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.
Merge activity
|
…abulary (#711) ## Summary Defines the script-graduation doctrine for Trails tooling and lands the binding vocabulary (TRL-933). - Adds `docs/contributing/script-graduation.md`: the two-question graduation model (whose truth is it; relationship + audience), the contract-first "shadow contract" rationale, the toolshed/house newcomer heuristic, worked examples (`vocab-cutover-rewrite` derives-but-stays-tooling; `release.check` derives-and-graduates), post-graduation wrapper guidance, and a review-checklist line for new/heavily-edited root scripts. - Adds `binding` to `docs/lexicon.md` as the genus, with `native binding` and `adapter binding` kinds set by the ADR-0029 dependency-boundary test, qualified-prose guidance, and the adapter-seam note (the seam is the shared extension and conformance path, not the public noun for every binding). - Reconciles the `store` and `kind` lexicon entries to binding-as-genus phrasing. - Adds a one-line ADR-0029 amendment note mapping the materializer/extracted distinction onto native binding vs adapter binding. - Wires pointers from `docs/contributing/README.md` and `AGENTS.md`. Docs-only; no publishable package content (release check passes with no changeset for this branch). Linear: TRL-933 ## Verification - `bun run check`, `bun run docs:wrap-check`, `bun run docs:links`, `bun run vocab:audit` all green at the stack tip.
graphite-app
Bot
force-pushed
the
trl-933-define-script-graduation-doctrine-for-trails-tooling
branch
from
6aca103 to
3f85361
Compare
graphite-app Bot
pushed a commit
that referenced
this pull request
Jun 9, 2026
## Summary Graduates scaffold-version sync into the `create` surface (TRL-942), applying the script-graduation doctrine from #711: the app owns `scaffold-versions.generated.ts`, so it now owns the derivation too. - New public `create.versions` trail (`trails create versions`): write mode regenerates `apps/trails/src/scaffold-versions.generated.ts` from the root `package.json` catalog/devDependencies; `--check` verifies it is current and fails actionably on drift. The `@ontrails/*` exact-pin invariant check rides along via a static import of the app's `versions.ts`. - Derivation lives in `apps/trails/src/scaffold-version-sync.ts`; the trail follows the `release.check` graduation precedent (`resolveTrailRootDir`, throw→`ValidationError`). - `scripts/sync-scaffold-versions.ts` is reduced to a thin compatibility wrapper that forwards to the trails CLI (with an inline `--permit`, the documented pattern for scripted invocations); `scaffold-versions:sync`/`:check` package scripts route through it so the wrapper stays a referenced entrypoint (knip-clean). - Test coverage moves to `apps/trails/src/__tests__/create-versions-trail.test.ts` (9 tests): the four ported pin-diagnostic cases plus write/check/drift/missing-dependency paths against temp roots. - Changeset: `@ontrails/trails` minor (new public trail). Linear: TRL-942 ## Verification - `bun test apps/trails/src/__tests__/create-versions-trail.test.ts` (9 pass), app typecheck clean - Drift end-to-end: mutated generated file → check exits 1 with regenerate guidance; restored - `bun run check`, `bun run build`, `bun run test`, `bun run publish:check`, `bun run wayfinder:dogfood`, `bun run changeset:check` green at the stack tip
graphite-app
Bot
deleted the
trl-933-define-script-graduation-doctrine-for-trails-tooling
branch
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.
Summary
Defines the script-graduation doctrine for Trails tooling and lands the binding vocabulary (TRL-933).
docs/contributing/script-graduation.md: the two-question graduation model (whose truth is it; relationship + audience), the contract-first "shadow contract" rationale, the toolshed/house newcomer heuristic, worked examples (vocab-cutover-rewritederives-but-stays-tooling;release.checkderives-and-graduates), post-graduation wrapper guidance, and a review-checklist line for new/heavily-edited root scripts.bindingtodocs/lexicon.mdas the genus, withnative bindingandadapter bindingkinds set by the ADR-0029 dependency-boundary test, qualified-prose guidance, and the adapter-seam note (the seam is the shared extension and conformance path, not the public noun for every binding).storeandkindlexicon entries to binding-as-genus phrasing.docs/contributing/README.mdandAGENTS.md.Docs-only; no publishable package content (release check passes with no changeset for this branch).
Linear: TRL-933
Verification
bun run check,bun run docs:wrap-check,bun run docs:links,bun run vocab:auditall green at the stack tip.