One authored descriptor per repo, projected to every surface and gated on drift.
descriptor-kit reads a repo's trellis.json descriptor block and projects it into managed README regions — header, where-it-fits, a git-pinned claims table, and links. descriptor check fails CI when the README drifts from the source, the same way prx generates its own README. This file is itself generated by descriptor-kit.
🟡 Partial — mechanism present; named gaps remain.
This README's header, "where it fits", claims table, and links are generated from
trellis.jsonby descriptor-kit itself.descriptor checkruns in CI and fails on drift — so this page cannot lie about the code.
Where it fits: guest-sdk tooling (tool). generate-and-gate for repo identity — the drift cure prx proved, made shared.
- Provides —
descriptor-schema,readme-projection - Consumes —
trellis-node
Across an org, hand-written READMEs drift from the code they describe: a shipped feature stays marked "deferred", a dependency pin goes stale, a claims table cites a test that was renamed. The one repo that never drifts is the one whose README is generated from source and gated in CI. descriptor-kit makes that pattern shared instead of bespoke.
One authored source per repo — the descriptor block inside trellis.json (the
same file that declares the repo's contract-lattice node) — projects to many
surfaces. Today: the README. Next: the org knowledge graph node, the org-map row,
and a bounded.tools product page. Author once, project everywhere, gate on drift.
Add a marker pair for each block you want managed, where ‹block› is one of
header, fit, claims, or links:
<!-- descriptor:‹block› start -->
<!-- descriptor:‹block› end -->Author the source in trellis.json (see this repo's own for the shape), then:
bunx @bounded-systems/descriptor-kit render . # fill the managed blocks
bunx @bounded-systems/descriptor-kit check . # exit 1 if the README has driftedWire check into CI (see .github/workflows/standard.yml) and drift becomes a
build failure. --run-suite additionally runs descriptor.proof.suite, so a claim
can't cite a test that isn't green. A managed block must appear exactly once — the
generator rejects duplicates, so keep examples like the one above using a placeholder.
Pinned at is the last-touching commit of each provenBy file, read from git at
render time — never hand-typed. And a claim whose provenBy file doesn't exist fails
the render outright. Stale pins and phantom claims become structurally impossible.
Every row is generated from descriptor.proof in trellis.json: the Proven by
file must exist, and Pinned at is its content digest (git blob hash) — it changes
iff the test content changes, so the table can't cite a missing test or a stale one.
| Claim | Proven by | Pinned at |
|---|---|---|
| The descriptor schema accepts well-formed nodes and rejects bad status / missing tagline / empty claims | src/__tests__/schema.test.ts |
7b0999095f66 |
bun test- repo — https://github.com/bounded-systems/descriptor-kit
- schema — src/schema.ts
Early. Projects README blocks today; the graph-node / org-map / product-page
projections and Zod-shared-with-trellis validation are the next steps. See the
descriptor schema in src/schema.ts.
MIT.