create-githolon 0.105.13 → 0.105.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.105.13",
+  "version": "0.105.14",
   "type": "module",
   "description": "Scaffold a Nomos domain package: the starter domain + compile config + live e2e. `npm create githolon my-app`.",
   "license": "SEE LICENSE IN LICENSE.md",

package/template/CLAUDE.md

@@ -10,11 +10,22 @@ Model the business language. Do not recreate Nomos as application infrastructure
 - Relationships use `t.ref(Aggregate)` and `idOf(Aggregate)`; generated code carries `NomosRef<Aggregate>`.
 - Pass the generated application through the UI as the sole business state. Do not add repositories, SQLite
   mirrors, runtime hosts, session providers, custom sync, ID stores, or replacement aggregate versions.
+- Treat `nomos.identity.usda` as the compiler-owned memory of committed identity. Do not edit stable IDs or
+  pass deployment waivers. When compile identifies a real breaking change, declare it separately in
+  `evolutions/<domain>/**/*.evolution.ts`; additions and inferred renames need no evolution file.
 
 ```bash
 npm run compile
 npm run proof
+# After the first deployed model, prove the candidate over copied real custody too:
+npx githolon proof --upgrade
 ```
 
+`compile` is the evolution gate. `proof` exercises the emitted candidate in the real local kernel, including
+cold custody restore. `proof --upgrade` resolves the workspace already bound in `nomos.project.ts`, copies
+its custody into a disposable local kernel, replays the candidate over the exact history, promotes it only
+in that copy, and cold-opens the result. If history changes meaning, it stops for an explicit
+`--acceptance-reason`; never invent one. Never make deployment the first place a candidate law is executed.
+
 If either command exposes framework implementation machinery, treat that as a Nomos defect rather than
 teaching the application to handle it.

package/template/README.md

@@ -63,9 +63,42 @@ npm run proof
 real local engine, discards resident state, restores it from durable custody, verifies its history, and reads
 the business world back.
 
+From the second compile onward, `compile` also compares the candidate with the committed
+`nomos.identity.usda`. Additions and inferred renames pass automatically. A removal, contract change, or
+merge-driver change stops locally with the exact declaration path and the evolution it needs; it cannot
+quietly become a deployment problem. Put that separate concern in
+`evolutions/<domain>/**/*.evolution.ts`, for example:
+
+```ts
+import { Lww, evolution, formerAggregate, retirement, t } from "@githolon/dsl";
+import { Asset } from "../../domains/estate.js";
+
+const formerAsset = formerAggregate("Asset", ["legacyCode"] as const);
+export const retireLegacyCode = retirement(formerAsset.fields.legacyCode);
+
+const formerName = t.enum(["unnamed", "named"] as const).merge(Lww);
+export const evolveAssetName = evolution(Asset, "name")
+  .from(formerName, value => value === "unnamed" ? "Unnamed asset" : "Named asset");
+```
+
+These files are discovered by compile and editor checks but are never loaded as application plans. Keep the
+updated identity file beside the domain source, run `proof`, and deploy only those locally proven bytes.
+
+Before upgrading an existing application, run the history-shaped proof as well:
+
+```bash
+npx githolon proof --upgrade
+```
+
+It uses the workspace binding in `nomos.project.ts` (or accepts a workspace/local-ledger argument), copies
+that custody into the local kernel, exercises the candidate against its exact history, promotes only in the
+copy, and proves a cold restart. The source is never modified. If the candidate deliberately changes an old
+business outcome, the command names the differences and requires an accountable `--acceptance-reason`.
+
 Useful files:
 
 - [`domains/estate.ts`](domains/estate.ts): nouns, private consequences, and public language;
+- `evolutions/`: explicit transitions from previously committed business law;
 - [`nomos.project.ts`](nomos.project.ts): typed business-law authoring input; it emits the readable USDA law closure and its `.law.usdz` package;
 - [`nomos.application.ts`](nomos.application.ts): application-composition authoring input; only the emitted `.application.usda` travels;
 - `build/application/__APP_DART_NAME___application/`: the sole Flutter application dependency;