@gadicc/loom 1.35.2 → 1.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/README.md +56 -0
  2. package/THIRD_PARTY_NOTICES.md +12 -9
  3. package/esm/src/cli/externalSkills.d.ts.map +1 -1
  4. package/esm/src/cli/externalSkills.js +25 -20
  5. package/esm/src/cli/mod.d.ts +72 -1
  6. package/esm/src/cli/mod.d.ts.map +1 -1
  7. package/esm/src/cli/mod.js +771 -36
  8. package/esm/src/cli/projectSkills.d.ts +10 -3
  9. package/esm/src/cli/projectSkills.d.ts.map +1 -1
  10. package/esm/src/cli/projectSkills.js +173 -49
  11. package/esm/src/cli/vercelBuildEnv.d.ts +28 -0
  12. package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
  13. package/esm/src/cli/vercelBuildEnv.js +120 -30
  14. package/esm/src/mail/postal.d.ts.map +1 -1
  15. package/esm/src/mail/postal.js +2 -1
  16. package/esm/src/next/secrets/mod.d.ts +108 -0
  17. package/esm/src/next/secrets/mod.d.ts.map +1 -0
  18. package/esm/src/next/secrets/mod.js +176 -0
  19. package/esm/src/secrets/encoding.d.ts +32 -0
  20. package/esm/src/secrets/encoding.d.ts.map +1 -0
  21. package/esm/src/secrets/encoding.js +87 -0
  22. package/esm/src/secrets/errors.d.ts +45 -0
  23. package/esm/src/secrets/errors.d.ts.map +1 -0
  24. package/esm/src/secrets/errors.js +39 -0
  25. package/esm/src/secrets/fingerprint.d.ts +43 -0
  26. package/esm/src/secrets/fingerprint.d.ts.map +1 -0
  27. package/esm/src/secrets/fingerprint.js +87 -0
  28. package/esm/src/secrets/frame.d.ts +34 -0
  29. package/esm/src/secrets/frame.d.ts.map +1 -0
  30. package/esm/src/secrets/frame.js +86 -0
  31. package/esm/src/secrets/keyring.d.ts +62 -0
  32. package/esm/src/secrets/keyring.d.ts.map +1 -0
  33. package/esm/src/secrets/keyring.js +160 -0
  34. package/esm/src/secrets/legacy.d.ts +60 -0
  35. package/esm/src/secrets/legacy.d.ts.map +1 -0
  36. package/esm/src/secrets/legacy.js +147 -0
  37. package/esm/src/secrets/maintenance.d.ts +173 -0
  38. package/esm/src/secrets/maintenance.d.ts.map +1 -0
  39. package/esm/src/secrets/maintenance.js +315 -0
  40. package/esm/src/secrets/mod.d.ts +6 -0
  41. package/esm/src/secrets/mod.d.ts.map +1 -0
  42. package/esm/src/secrets/mod.js +5 -0
  43. package/esm/src/secrets/secrets.d.ts +192 -0
  44. package/esm/src/secrets/secrets.d.ts.map +1 -0
  45. package/esm/src/secrets/secrets.js +528 -0
  46. package/package.json +50 -2
  47. package/script/src/cli/externalSkills.d.ts.map +1 -1
  48. package/script/src/cli/externalSkills.js +25 -20
  49. package/script/src/cli/mod.d.ts +72 -1
  50. package/script/src/cli/mod.d.ts.map +1 -1
  51. package/script/src/cli/mod.js +772 -33
  52. package/script/src/cli/projectSkills.d.ts +10 -3
  53. package/script/src/cli/projectSkills.d.ts.map +1 -1
  54. package/script/src/cli/projectSkills.js +173 -49
  55. package/script/src/cli/vercelBuildEnv.d.ts +28 -0
  56. package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
  57. package/script/src/cli/vercelBuildEnv.js +121 -30
  58. package/script/src/mail/postal.d.ts.map +1 -1
  59. package/script/src/mail/postal.js +2 -1
  60. package/script/src/next/secrets/mod.d.ts +108 -0
  61. package/script/src/next/secrets/mod.d.ts.map +1 -0
  62. package/script/src/next/secrets/mod.js +218 -0
  63. package/script/src/secrets/encoding.d.ts +32 -0
  64. package/script/src/secrets/encoding.d.ts.map +1 -0
  65. package/script/src/secrets/encoding.js +95 -0
  66. package/script/src/secrets/errors.d.ts +45 -0
  67. package/script/src/secrets/errors.d.ts.map +1 -0
  68. package/script/src/secrets/errors.js +45 -0
  69. package/script/src/secrets/fingerprint.d.ts +43 -0
  70. package/script/src/secrets/fingerprint.d.ts.map +1 -0
  71. package/script/src/secrets/fingerprint.js +92 -0
  72. package/script/src/secrets/frame.d.ts +34 -0
  73. package/script/src/secrets/frame.d.ts.map +1 -0
  74. package/script/src/secrets/frame.js +91 -0
  75. package/script/src/secrets/keyring.d.ts +62 -0
  76. package/script/src/secrets/keyring.d.ts.map +1 -0
  77. package/script/src/secrets/keyring.js +202 -0
  78. package/script/src/secrets/legacy.d.ts +60 -0
  79. package/script/src/secrets/legacy.d.ts.map +1 -0
  80. package/script/src/secrets/legacy.js +186 -0
  81. package/script/src/secrets/maintenance.d.ts +173 -0
  82. package/script/src/secrets/maintenance.d.ts.map +1 -0
  83. package/script/src/secrets/maintenance.js +323 -0
  84. package/script/src/secrets/mod.d.ts +6 -0
  85. package/script/src/secrets/mod.d.ts.map +1 -0
  86. package/script/src/secrets/mod.js +24 -0
  87. package/script/src/secrets/secrets.d.ts +192 -0
  88. package/script/src/secrets/secrets.d.ts.map +1 -0
  89. package/script/src/secrets/secrets.js +532 -0
  90. package/skills/loom/SKILL.md +74 -222
  91. package/skills/loom/references/dependency-upgrades.md +26 -0
  92. package/skills/loom/references/local-development.md +157 -0
  93. package/skills/loom/references/release-safety.md +118 -0
  94. package/skills/loom/references/release-trusted-sources.md +55 -0
  95. package/skills/loom/references/tools-and-skills.md +83 -0
  96. package/skills/loom-api-keys/SKILL.md +1 -1
  97. package/skills/loom-auth/SKILL.md +7 -60
  98. package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
  99. package/skills/loom-db/SKILL.md +4 -79
  100. package/skills/loom-files/SKILL.md +4 -2
  101. package/skills/loom-files/references/provider-configuration.md +142 -0
  102. package/skills/loom-jobs/SKILL.md +9 -8
  103. package/skills/loom-lingui/SKILL.md +5 -3
  104. package/skills/loom-secrets/SKILL.md +252 -0
  105. package/skills/loom-torvalds-review/SKILL.md +9 -6
  106. package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
  107. package/skills/upgrade-deps/SKILL.md +15 -7
@@ -0,0 +1,252 @@
1
+ ---
2
+ name: loom-secrets
3
+ description: Use when the task touches the Loom secrets feature, @gadicc/loom/secrets or @gadicc/loom/next/secrets, sealed strings (ls1.), keyed fingerprints (lm1.), LOOM_SECRETS_KEY_ variables, key rotation, assertReady, reseal or verify jobs, or storing third-party credentials, tokens or TOTP seeds that the app must later read back.
4
+ ---
5
+
6
+ # Loom Secrets
7
+
8
+ Use this skill when an app stores values it must later use in clear: provider
9
+ passwords and API keys, saved sessions, TOTP seeds, short-lived tokens handed to
10
+ a caller, or fingerprints for matching a value without storing it.
11
+
12
+ Passwords the app only verifies are not secrets in this sense. Hash them.
13
+
14
+ ## Start here
15
+
16
+ 1. Read `loom.json` and inspect `features.secrets.config`: the wrapper module,
17
+ the locations module, the variable names and the production key list.
18
+ 2. Read the wrapper module. Every purpose the app uses is declared there.
19
+ 3. Read the locations module. Every column that holds a sealed string must be
20
+ declared there, or it is not reported, verified or resealed.
21
+
22
+ ## What it protects, and what it does not
23
+
24
+ - It protects against the database being read on its own: a dump, a backup, a
25
+ branch, console access.
26
+ - It makes the app refuse a value presented for a different purpose, owner or
27
+ bound destination.
28
+ - It does **not** protect against code running in the app, or anyone who can
29
+ deploy to the project or read its environment.
30
+ - It does **not** contain someone who can edit the rows the app trusts for where
31
+ to send a credential, unless that destination is in the binding.
32
+ - It does **not** stop an older valid value of the same row being put back.
33
+
34
+ Do not describe it as more than this in an app's docs or UI.
35
+
36
+ ## Never do these
37
+
38
+ - **Never run `loom secrets keygen` for a production key, and never ask for its
39
+ output.** A production key must exist in exactly two places: the operator's
40
+ password manager and the deployment platform. An agent's transcript is a
41
+ third. Ask the operator to run it in their own terminal, then continue from
42
+ the fingerprint, which is not secret. The same goes for
43
+ `loom secrets fingerprint`, which prompts for a key. Both commands refuse to
44
+ run when they detect a CI or agent session or a missing terminal. That is a
45
+ guardrail, not a guarantee: do not look for a way to satisfy it. The rule
46
+ holds whether or not the command would run.
47
+ - **Never pass a key as a command-line argument**, to `fingerprint` or anything
48
+ else. A key typed there is in shell history: treat it as exposed and rotate.
49
+ - **Never read, print, log or commit a key**: not `.env.local`, not a
50
+ `LOOM_SECRETS_KEY_*` or `CRYPTO_KEY_*` value, not in a test, not in
51
+ `loom.json`. `loom.json` holds fingerprints only.
52
+ - **Never set `allowDuringBuild` to make a failing build pass.** Make the route
53
+ dynamic.
54
+ - **Never pass `allowUnverifiedKeys` to a reseal against a production
55
+ database**, and never set `allowUnverifiedProduction` to make a health check
56
+ pass. Both exist because moving rows onto a key that was never shown to match
57
+ its fingerprint, and later retiring the old key, loses every row.
58
+ - **Never write another format beside it**, and never write the legacy
59
+ `(value, iv)` format: `@gadicc/loom/secrets/legacy` is read-only on purpose.
60
+ - **Never delete an entry from the key list or reuse its version number.**
61
+
62
+ ## Using it
63
+
64
+ ```ts
65
+ // the wrapper module
66
+ import { createNextSecrets } from "@gadicc/loom/next/secrets";
67
+ import loomManifest from "../loom.json";
68
+
69
+ const config = loomManifest.features.secrets.config;
70
+ export const secrets = createNextSecrets({
71
+ expectedKeys: config.keys,
72
+ variables: config.env,
73
+ });
74
+ export const forumApiKey = secrets.purpose("temple-forum.api-key");
75
+ ```
76
+
77
+ ```ts
78
+ await forumApiKey.seal(value, { temple: templeId, origin });
79
+ await forumApiKey.tryOpen(stored, { temple: templeId, origin });
80
+ ```
81
+
82
+ - **One purpose per kind of value.** Names are permanent identifiers:
83
+ `connection.password`, not `password`.
84
+ - **Always bind.** Bind to the owner (a row id, and the user where there is one)
85
+ and, where a secret has one stable destination, to that destination. Use
86
+ identifiers the app never transforms: no case folding, no URL tidying.
87
+ - **Changing which fields a purpose is bound to is a new purpose name.**
88
+ Changing the _value_ of a bound field is different: if it can be edited
89
+ without the secret being entered again, open with the old binding and seal
90
+ with the new one inside the same transaction.
91
+ - **Generate ids in the app** when a binding needs the id of a row that is being
92
+ inserted.
93
+ - **`open` throws one opaque error.** Its `reason` is for server logs. Never
94
+ show it to a user or return it from an API. Use `tryOpen` when "unreadable" is
95
+ a state the UI handles.
96
+ - **Parse JSON with `openJson`**, not `JSON.parse(await open(…))`: a
97
+ `SyntaxError` message quotes the plaintext.
98
+ - **Tokens** are a purpose with `ttlSeconds` and a small `maxLength`. Loom
99
+ enforces the lifetime. Replay, revocation and what the token authorises are
100
+ the app's job, so keep checking kind, user and session inside the payload.
101
+ - **Do not log** plaintext, sealed strings or bindings.
102
+
103
+ ### Next.js
104
+
105
+ - Secrets are unavailable while `next build` prerenders. Every operation,
106
+ including `tryOpen`, rejects with `SecretsBuildPhaseError`. A route that uses
107
+ secrets must be dynamic.
108
+ - The refusal covers the build only. A route that caches its output at run time
109
+ (`revalidate`, `use cache`) caches whatever it decrypted. Do not cache a
110
+ response that contains a secret.
111
+ - The key list that applies comes from `LOOM_SECRETS_ENVIRONMENT`, then
112
+ `VERCEL_ENV`. A host other than Vercel must set
113
+ `LOOM_SECRETS_ENVIRONMENT=production` in the platform's own environment, which
114
+ takes precedence over `.env` files. To run a production build locally, set it
115
+ to `development` in `.env.local`; `loom add secrets` writes that.
116
+ - For that reason `.env*.local` files must be excluded from container images and
117
+ deployments (`.dockerignore`, the platform's ignore file). A deployed
118
+ `.env.local` would otherwise declare the host to be `development`.
119
+ - If `LOOM_SECRETS_ENVIRONMENT` and `VERCEL_ENV` name different environments,
120
+ every operation is refused. Fix the variable; do not pass an `environment`
121
+ option to silence it.
122
+ - `loom.json`'s `env` section holds variable names and goes in `variables`. The
123
+ option for the object keys are read from is `keysEnv`, which an app rarely
124
+ needs; there is no `env` option.
125
+ - `loom check` requires the secrets module of a Next.js app to import
126
+ `@gadicc/loom/next/secrets`. The core `@gadicc/loom/secrets` has no build
127
+ refusal and no environment-selected key list.
128
+
129
+ ### Health check
130
+
131
+ Call `secrets.assertReady()` from a dynamic route and hit it from the release
132
+ smoke test. In production it rejects unless every recorded key is present and
133
+ matches its fingerprint and the pointer is on the active key. That is the only
134
+ proof that the deployed key is the one in the password manager. If the app
135
+ reports the result, require `verified === true` in production.
136
+
137
+ ### Keyed fingerprints
138
+
139
+ `mac(text, binding)` is deterministic and uses the text exactly as given.
140
+
141
+ - A fingerprint is **not** a stable lookup key across a rotation. To find a
142
+ stored entry, compare with `macMatches(stored, text, binding)`, or compute
143
+ under each key still in use with `mac(text, binding, { keyId })`.
144
+ - When `macNeedsRefresh(stored)` is true and the text is at hand, store a new
145
+ fingerprint.
146
+ - Seal the input beside the value it indexes, so the fingerprint can be
147
+ recomputed. Otherwise the old key can never be retired.
148
+ - Equal text under an equal binding gives equal fingerprints, visible to anyone
149
+ who can read them. Put an owner in the binding where that matters.
150
+
151
+ ## Keys
152
+
153
+ ```
154
+ LOOM_SECRETS_KEY_1=… # write-only secret, Production only
155
+ LOOM_SECRETS_ACTIVE_KEY=1 # readable
156
+ ```
157
+
158
+ - One variable per key version and a required pointer. Different keys per
159
+ environment. Never share a key between apps.
160
+ - Production fingerprints are recorded in `loom.json` with a state: `active`,
161
+ `decrypt-only` or `retired`. Use `loom secrets activate` and
162
+ `loom secrets retire` to change states rather than editing by hand.
163
+ - Development keys are written to `.env.local` by `loom add secrets` and are not
164
+ recorded. `vercel env pull` rewrites `.env.local` and can drop them; run
165
+ `loom add secrets` again. Locally sealed rows are then unreadable, which is
166
+ fine for development data.
167
+
168
+ ### Rotation
169
+
170
+ 1. Operator: `loom secrets keygen`, which records the new key as `decrypt-only`.
171
+ Save the key and fingerprint in the password manager.
172
+ 2. Operator: add `LOOM_SECRETS_KEY_<n+1>` to the platform from the
173
+ password-manager copy, as a write-only secret for Production only. Deploy.
174
+ The health check must pass.
175
+ 3. Move the pointer, in this order. Operator: set
176
+ `LOOM_SECRETS_ACTIVE_KEY=<n+1>` on the platform **first**. Then
177
+ `loom secrets activate <n+1>`, run `loom check --production`, and push the
178
+ `loom.json` change, so the deployment that carries the new list is built with
179
+ the new pointer. In the other order, a deployment with the new list and the
180
+ old pointer fails every `seal`, `reseal` and `mac` (opens still work). Then
181
+ delete deployments built before step 2: an older deployment keeps the
182
+ environment it was built with and cannot read the new rows.
183
+ 4. Run `reseal` (a real run needs `dryRun: false`), then `report`, then
184
+ `verify`.
185
+ 5. Retiring the old key is a separate decision. It is safe only when:
186
+ - `report` shows no row under it, with every location `done`;
187
+ - no keyed fingerprint is still under it (`report` does not count those);
188
+ - expired values under it have been deleted, since they can never be
189
+ resealed;
190
+ - no restorable database backup needs it.
191
+
192
+ Then `loom secrets retire <n>` and deploy that `loom.json` **before**
193
+ removing the variable: while a deployed list still expects the key,
194
+ `assertReady()` fails with "not configured" once the variable is gone. After
195
+ that, remove its variable and delete every deployment built while it was
196
+ active. Keep the list entry and the password-manager copy.
197
+
198
+ After a suspected compromise, also change the stored credentials at their
199
+ providers. Resealing does not un-leak them.
200
+
201
+ ### A key that was recorded but never saved
202
+
203
+ `keygen` records the fingerprint in `loom.json` before the operator has saved
204
+ the key. If the key was lost first (the terminal was closed, the paste failed):
205
+
206
+ 1. Operator: `loom secrets keygen` again. It takes the next version.
207
+ 2. `loom secrets activate <new>`, then deploy it as in the rotation above.
208
+ 3. `loom secrets retire <lost>`.
209
+
210
+ The lost version's entry stays in the list, retired, and fails closed at run
211
+ time. Do not delete the entry or reuse its number. There is no un-retire: a
212
+ retired version cannot be activated again, so retire only a key that is truly
213
+ gone or no longer needed.
214
+
215
+ ## Maintenance
216
+
217
+ - `reportSecretLocations` counts rows per key version without decrypting, so it
218
+ needs no key.
219
+ - `verifySecretLocations` opens every row strictly and names the rows that do
220
+ not open.
221
+ - `resealSecretLocations` moves rows to the active key. It is a dry run unless
222
+ `dryRun: false`. It first runs `assertReady()` for each location's purpose,
223
+ and a real run refuses unless the keys were verified against the recorded
224
+ list.
225
+
226
+ `verify` and `reseal` must run inside the deployed app, behind admin
227
+ authorization, because the keys exist nowhere else.
228
+
229
+ Reading results: a location is finished only when `done` is true. A clean run
230
+ has `failureCount` 0 and, for reseal, `changed` 0; a changed row was left alone
231
+ and is still under its old key, so run again. To continue a run that stopped at
232
+ `maxRows`, pass its results back as `previous`.
233
+
234
+ A location's `write` is one `UPDATE … WHERE` and never an insert. Build a
235
+ location's binding with the same function the app's reader uses.
236
+
237
+ ## What to preserve
238
+
239
+ - Purpose names and bindings of existing data.
240
+ - Every entry in the production key list in `loom.json`.
241
+ - Any `CRYPTO_KEY_<n>` variable an app still reads through the legacy reader.
242
+ - The release policy entries `loom check` asks for: a `keyPattern` requirement
243
+ that keeps the secrets keys Production-only write-only secrets, and a `keys`
244
+ requirement for the pointer variable (`LOOM_SECRETS_ACTIVE_KEY`).
245
+
246
+ ## Verification
247
+
248
+ - Tests inject keys with `staticKeyring({ 1: bytes })` and a clock. Use
249
+ obviously synthetic keys, never a real one.
250
+ - Run `loom check`, and `loom check --production` before a release.
251
+ - After changing where sealed strings are stored, update the locations module
252
+ and run `verify`.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: loom-torvalds-review
3
- description: Context-aware code and design review for Loom consumer projects, adapting the linus-torvalds-skill reviewer method to the actual runtime and product contract. Use when reviewing a diff or pull request, assessing an API or architecture change, checking a refactor or bug fix, challenging a performance claim, or doing the final engineering review of implementation work, especially in Next.js and other web applications.
3
+ description: Review Loom code and designs using the actual product and runtime contracts. Adapts the upstream Torvalds method for web apps, libraries, CLI and native code.
4
4
  ---
5
5
 
6
6
  # Loom Torvalds Review
@@ -20,8 +20,9 @@ corpus-derived severity rates, or Linus Torvalds's persona as universal rules.
20
20
  repository's explicit contract.
21
21
  3. For a code or design review, read
22
22
  `.agents/skills/linus-torvalds-skill/SKILL.md` when it is installed. Treat
23
- its triggers as a source of review questions, not automatic findings. Do not
24
- load or imitate an upstream `soul` or persona file.
23
+ only this entrypoint, not the GLM/Mistral variants or a `soul`/persona file.
24
+ Treat its triggers, verdict tables, decision trees, simplified workflows and
25
+ severity percentages as questions, never automatic findings or binding rules.
25
26
  4. If the upstream skill is not installed, continue with this skill. Mention
26
27
  `loom add skills` only when the missing deeper review catalog materially
27
28
  limits the task.
@@ -76,9 +77,11 @@ kernel convention above security or supported users.
76
77
  4. Check the actual diff for unrelated churn, compatibility changes, hidden
77
78
  costs, unnecessary special cases, inaccurate docs, and missing cleanup
78
79
  created by the change.
79
- 5. Seek proportionate evidence. Reproduce correctness failures; use realistic
80
- measurements for performance claims; run the repository's relevant tests,
81
- typecheck, lint, and build when implementation work is in scope.
80
+ 5. Seek proportionate evidence. Establish correctness failures through a
81
+ concrete source trace or a permitted reproduction; use realistic measurements
82
+ for performance claims; run the repository's relevant tests, typecheck, lint,
83
+ and build when implementation work is in scope. A read-only review does not
84
+ require mutations or extra agents; disclose verification gaps.
82
85
  6. Derive severity from concrete impact and reachability. Ignore the upstream
83
86
  corpus percentages when deciding whether a finding blocks the change.
84
87
 
@@ -84,7 +84,8 @@ same: what real contract or failure mode does this rule protect here?
84
84
  Isolate unavoidable Node or native behavior and test the supported runtimes.
85
85
  - Apply bisectability to the commits that will be shipped. A working tree need
86
86
  not be valid at every keystroke, while each final commit should build and make
87
- coherent sense when the repository requires that history quality.
87
+ coherent sense. Follow Loom's applicable full-suite evidence rule before code
88
+ commits and preserve the repository's stronger build gates.
88
89
  - Require benchmarks only for performance claims or budgets that affect package
89
90
  users. Include startup time, artifact size, throughput, memory, and generated
90
91
  client-bundle impact when relevant.
@@ -10,7 +10,9 @@ prove each meaningful change, and leave intentional deferrals documented.
10
10
 
11
11
  ## 1. Establish the contract
12
12
 
13
- 1. Read repository instructions before changing files.
13
+ 1. Read repository instructions and distinguish an inventory-only request from
14
+ an authorized upgrade. Read-only inventory does not require installs or
15
+ gates.
14
16
  2. Inspect the manifests, lockfiles, dependency-manager declarations, runtime
15
17
  versions, CI workflows, and available verification scripts. Keep the existing
16
18
  dependency manager unless the user explicitly requests a migration.
@@ -18,9 +20,10 @@ prove each meaningful change, and leave intentional deferrals documented.
18
20
  Do not rely on destructive rollback commands in a dirty tree.
19
21
  4. Identify generated files and their source commands. Regenerate them through
20
22
  the project workflow rather than editing them manually.
21
- 5. Run the strongest practical baseline: install or lockfile validation,
22
- formatting/lint, typecheck, tests, build, and project-specific checks. Record
23
- existing warnings and flaky behavior so they are not attributed to upgrades.
23
+ 5. Before implementation, establish the strongest practical baseline: install or
24
+ lockfile validation, formatting/lint, typecheck, tests, build, and
25
+ project-specific checks. Record existing warnings and flaky behavior so they
26
+ are not attributed to upgrades.
24
27
 
25
28
  If the project consumes Loom, use the `loom` skill first, read `loom.json`, use
26
29
  feature skills affected by the upgrade, and include `loom check --production` in
@@ -150,11 +153,16 @@ Follow the repository's commit-message and attribution rules.
150
153
 
151
154
  ## 8. Run the exact-tree final gate
152
155
 
153
- After formatting or commit hooks have finished, verify the exact final tree:
156
+ Format before the final gate. Have evidence for the exact content being
157
+ committed; do not rely on unstaged fixes. Preserve user-owned changes using an
158
+ isolated snapshot when necessary, never an automatic stash or reset.
159
+
160
+ For the final tree:
154
161
 
155
162
  1. Confirm manifest and lockfile consistency across the project or workspace.
156
- 2. Run required generators, lint/format, typecheck, full tests, production
157
- build, and project-specific checks.
163
+ 2. Have passing required generators, lint/format, typecheck, full tests,
164
+ production build, and project-specific checks. Reuse evidence only while its
165
+ inputs are unchanged; edits or hooks that change them invalidate it.
158
166
  3. Inspect the final status and diff for unrelated changes.
159
167
  4. Re-run the outdated inventory when registry access is available.
160
168
  5. Report successful upgrades, migrations, removals, deferred packages with