Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/commands/feature.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ There is no `test:changed`-style command here, and there should not be: a comman

Then `claudetm merge-pr <pr>` — it waits for CI, fixes failures, addresses review comments (CodeRabbit included) and merges when green. It operates on the **current directory**, so at most one PR is in flight: parallel *building* is fine, parallel *merging* is not. **When every check already passes, prefer `gh pr merge --squash`** — `claudetm` can hang on an already-green PR. Gotcha: **0 registered checks reads as "pass"** — wait until the count is plausible *and* nothing is pending, or you merge RED right after a rebase.

10. **Release + close.** Nothing deploys — this is a framework. `wiki.yml` syncs `wiki/` on merge, so confirm it ran if you touched the wiki. An npm release is deliberate and only when asked or when the change is user-facing and complete: publishing goes through **OIDC trusted publishing**, no `NPM_TOKEN` — follow [`PUBLISHING.md`](../../PUBLISHING.md), then confirm the published version matches. Otherwise say so and stop at merged. Verify each `Fixes #NNN` actually closed, and close any straggler with a link to the merged PR.
10. **Release + close.** Nothing deploys — this is a framework. `wiki.yml` syncs `wiki/` on merge, so confirm it ran if you touched the wiki. An npm release is deliberate and only when asked or when the change is user-facing and complete: publishing goes through **OIDC trusted publishing** — follow [`PUBLISHING.md`](../../PUBLISHING.md), then confirm the published version matches. Otherwise say so and stop at merged. Verify each `Fixes #NNN` actually closed, and close any straggler with a link to the merged PR.

## Hard rules (from CLAUDE.md — non-negotiable)

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: release

# Publishes every @ultimat3 package to npm using OIDC trusted publishing — no NPM_TOKEN secret.
# Publishes every @ultimat3 package to npm using OIDC trusted publishing.
# npm mints a short-lived token from the GitHub Actions id-token and verifies it against the
# trusted publisher configured for each package on npmjs.com. Provenance is automatic.
#
Expand Down
8 changes: 6 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ CLI binary: `x`. npm scope: `@ultimat3`. Import paths: `@ultimat3/<pkg>`.
**Status:** 1.2.0, `As of 2026-08`. 28 `@ultimat3/*` packages plus the unscoped `create-ultimate` —
29 in all — on npm in lockstep: one version, one commit, one tag. 1.1.0 was the first
release published by [`.github/workflows/release.yml`](.github/workflows/release.yml) over OIDC
trusted publishing, no `NPM_TOKEN`, provenance attached; 1.0.0 was the manual bootstrap. Semver
trusted publishing, provenance attached; 1.0.0 was the manual bootstrap. Semver
applies — a breaking change to a documented API needs a major, and the eight primitive shapes, the
`x` CLI surface and the tier table are as stable as the `X_*` codes already were.

Expand Down Expand Up @@ -52,6 +52,10 @@ Milestone detail: [`docs/idea/14-roadmap.md`](docs/idea/14-roadmap.md).
5. **One command means shippable.** `x verify` is the contract.
6. **Static path never pays for the app path.** Separate bundle graphs, hard boundaries.
7. **Deploy anywhere = containers only.** Zero platform primitives in the framework.
8. **Ultimate ships mechanism; your app ships convention.** Mechanisms and *structural* conventions
ship — the same for a bank and a blog. *Business* conventions never do. Primitives are functions
returning values, so an app encodes its own by wrapping one: no fork, no patch, no plugin API.
[`docs/idea/19-mechanism-not-convention.md`](docs/idea/19-mechanism-not-convention.md).

## Commands

Expand Down Expand Up @@ -167,7 +171,7 @@ Everything in the framework is one of these. **If a feature doesn't fit one of t

## CI

Free GitHub Actions runners (`ubuntu-latest`) — never a paid runner. `ci.yml` runs three jobs, each answering a question no other job answers: `verify` (the gate, `x verify` verbatim — lint, typecheck, boundaries and every suite are its steps, never a second job), `reference-app-verify` (the app gate, on its ratchet) and `scaffold-smoke` (`x new` → `bun install` → `x verify` outside the checkout). Target under 5 minutes. Every job starts with `./.github/actions/setup` — bun, the install cache, a frozen install. Releases publish to npm via **OIDC trusted publishing**, no `NPM_TOKEN` — see [`PUBLISHING.md`](PUBLISHING.md).
Free GitHub Actions runners (`ubuntu-latest`) — never a paid runner. `ci.yml` runs three jobs, each answering a question no other job answers: `verify` (the gate, `x verify` verbatim — lint, typecheck, boundaries and every suite are its steps, never a second job), `reference-app-verify` (the app gate, on its ratchet) and `scaffold-smoke` (`x new` → `bun install` → `x verify` outside the checkout). Target under 5 minutes. Every job starts with `./.github/actions/setup` — bun, the install cache, a frozen install. Releases publish to npm via **OIDC trusted publishing**, with provenance — see [`PUBLISHING.md`](PUBLISHING.md).

## Note

Expand Down
2 changes: 1 addition & 1 deletion PUBLISHING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Every framework package publishes to npm under the **`@ultimat3`** scope. `creat
unscoped, because `bunx create-ultimate myapp` is the first command a user ever runs.

Releases use **OIDC trusted publishing** from GitHub Actions
([`.github/workflows/release.yml`](.github/workflows/release.yml)) — no `NPM_TOKEN` secret. npm
([`.github/workflows/release.yml`](.github/workflows/release.yml)). npm
mints a short-lived token from the run's OIDC identity and attaches a provenance attestation
automatically.

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

</div>

> **Status: 1.1.0**, `As of 2026-08`. 27 `@ultimat3/*` packages plus the unscoped `create-ultimate` — 28 in all — on npm in lockstep: one version, one commit, one tag. 1.1.0 is the **first release published by the workflow**, over OIDC trusted publishing with no `NPM_TOKEN` and provenance attached; 1.0.0 was the manual bootstrap. Semver applies — a breaking change to a documented API needs a major. That is what the version number means: a stable API under semver, not a promise about your infrastructure.
> **Status: 1.2.0**, `As of 2026-08`. 28 `@ultimat3/*` packages plus the unscoped `create-ultimate` — 29 in all — on npm in lockstep: one version, one commit, one tag. 1.1.0 was the **first release published by the workflow**, over OIDC trusted publishing with provenance attached; 1.0.0 was the manual bootstrap. Semver applies — a breaking change to a documented API needs a major. That is what the version number means: a stable API under semver, not a promise about your infrastructure.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

**Measured, and only this much:**

Expand Down
5 changes: 4 additions & 1 deletion docs/idea/00-thesis.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ The rule that keeps this from becoming an abstraction tower: **a wrapper must de

Reinventing is reserved for where the wrap would leak the thing being avoided: there is no ORM, because an ORM's abstraction is exactly the thing that has to be understood to debug it.

Which layer owns a given decision is [axiom 8](#design-axioms): Ultimate ships mechanism, your app ships convention. The mechanism / structural-convention / business-convention split, the worked decisions, and why the third row of that table needs no plugin API are in [`19-mechanism-not-convention.md`](./19-mechanism-not-convention.md).

## Pre-MVP to planet-scale, without a rewrite

The same app code runs on one PaaS dyno and on a distributed cluster. Climbing is a driver swap and configuration — never a re-architecture. That is the promise the whole design is arranged around, and the rungs, seams and honest incompatibilities are in [`17-scale-ladder.md`](./17-scale-ladder.md).
Expand All @@ -72,8 +74,9 @@ Non-negotiable. Every package, doc, and generated file honours these.
| 5 | **One command means shippable.** | `x verify` green = deployable. No tribal checklist, no "also run the e2e suite on staging". |
| 6 | **Static path never pays for the app path.** | Separate bundle graphs; `site/` cannot import `app/`. 0kb JS baseline on marketing is structural, not aspirational. |
| 7 | **Deploy anywhere = containers only.** | Zero platform primitives. No edge functions, no vendor KV, no proprietary image loader. If it needs a specific host, it isn't in the framework. |
| 8 | **Ultimate ships mechanism; your app ships convention.** | Mechanisms ship, and so do *structural* conventions — file naming, the four surfaces, the tier order, one catalog per locale — because they are the same for a bank and a blog. *Business* conventions never ship: tenancy is a mechanism, an org model is somebody's business. Primitives are functions returning values, so an app encodes its own by wrapping one — no fork, no monkey-patch, no plugin API. |

See [`02-primitives.md`](./02-primitives.md) for how axiom 2 is implemented and [`10-testing.md`](./10-testing.md) for axiom 5's contents.
See [`02-primitives.md`](./02-primitives.md) for how axiom 2 is implemented, [`10-testing.md`](./10-testing.md) for axiom 5's contents, and [`19-mechanism-not-convention.md`](./19-mechanism-not-convention.md) for axiom 8's test and its worked decisions.

## Explicit exclusions

Expand Down
Loading
Loading