@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.
- package/README.md +56 -0
- package/THIRD_PARTY_NOTICES.md +12 -9
- package/esm/src/cli/externalSkills.d.ts.map +1 -1
- package/esm/src/cli/externalSkills.js +25 -20
- package/esm/src/cli/mod.d.ts +72 -1
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +771 -36
- package/esm/src/cli/projectSkills.d.ts +10 -3
- package/esm/src/cli/projectSkills.d.ts.map +1 -1
- package/esm/src/cli/projectSkills.js +173 -49
- package/esm/src/cli/vercelBuildEnv.d.ts +28 -0
- package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/esm/src/cli/vercelBuildEnv.js +120 -30
- package/esm/src/mail/postal.d.ts.map +1 -1
- package/esm/src/mail/postal.js +2 -1
- package/esm/src/next/secrets/mod.d.ts +108 -0
- package/esm/src/next/secrets/mod.d.ts.map +1 -0
- package/esm/src/next/secrets/mod.js +176 -0
- package/esm/src/secrets/encoding.d.ts +32 -0
- package/esm/src/secrets/encoding.d.ts.map +1 -0
- package/esm/src/secrets/encoding.js +87 -0
- package/esm/src/secrets/errors.d.ts +45 -0
- package/esm/src/secrets/errors.d.ts.map +1 -0
- package/esm/src/secrets/errors.js +39 -0
- package/esm/src/secrets/fingerprint.d.ts +43 -0
- package/esm/src/secrets/fingerprint.d.ts.map +1 -0
- package/esm/src/secrets/fingerprint.js +87 -0
- package/esm/src/secrets/frame.d.ts +34 -0
- package/esm/src/secrets/frame.d.ts.map +1 -0
- package/esm/src/secrets/frame.js +86 -0
- package/esm/src/secrets/keyring.d.ts +62 -0
- package/esm/src/secrets/keyring.d.ts.map +1 -0
- package/esm/src/secrets/keyring.js +160 -0
- package/esm/src/secrets/legacy.d.ts +60 -0
- package/esm/src/secrets/legacy.d.ts.map +1 -0
- package/esm/src/secrets/legacy.js +147 -0
- package/esm/src/secrets/maintenance.d.ts +173 -0
- package/esm/src/secrets/maintenance.d.ts.map +1 -0
- package/esm/src/secrets/maintenance.js +315 -0
- package/esm/src/secrets/mod.d.ts +6 -0
- package/esm/src/secrets/mod.d.ts.map +1 -0
- package/esm/src/secrets/mod.js +5 -0
- package/esm/src/secrets/secrets.d.ts +192 -0
- package/esm/src/secrets/secrets.d.ts.map +1 -0
- package/esm/src/secrets/secrets.js +528 -0
- package/package.json +50 -2
- package/script/src/cli/externalSkills.d.ts.map +1 -1
- package/script/src/cli/externalSkills.js +25 -20
- package/script/src/cli/mod.d.ts +72 -1
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +772 -33
- package/script/src/cli/projectSkills.d.ts +10 -3
- package/script/src/cli/projectSkills.d.ts.map +1 -1
- package/script/src/cli/projectSkills.js +173 -49
- package/script/src/cli/vercelBuildEnv.d.ts +28 -0
- package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/script/src/cli/vercelBuildEnv.js +121 -30
- package/script/src/mail/postal.d.ts.map +1 -1
- package/script/src/mail/postal.js +2 -1
- package/script/src/next/secrets/mod.d.ts +108 -0
- package/script/src/next/secrets/mod.d.ts.map +1 -0
- package/script/src/next/secrets/mod.js +218 -0
- package/script/src/secrets/encoding.d.ts +32 -0
- package/script/src/secrets/encoding.d.ts.map +1 -0
- package/script/src/secrets/encoding.js +95 -0
- package/script/src/secrets/errors.d.ts +45 -0
- package/script/src/secrets/errors.d.ts.map +1 -0
- package/script/src/secrets/errors.js +45 -0
- package/script/src/secrets/fingerprint.d.ts +43 -0
- package/script/src/secrets/fingerprint.d.ts.map +1 -0
- package/script/src/secrets/fingerprint.js +92 -0
- package/script/src/secrets/frame.d.ts +34 -0
- package/script/src/secrets/frame.d.ts.map +1 -0
- package/script/src/secrets/frame.js +91 -0
- package/script/src/secrets/keyring.d.ts +62 -0
- package/script/src/secrets/keyring.d.ts.map +1 -0
- package/script/src/secrets/keyring.js +202 -0
- package/script/src/secrets/legacy.d.ts +60 -0
- package/script/src/secrets/legacy.d.ts.map +1 -0
- package/script/src/secrets/legacy.js +186 -0
- package/script/src/secrets/maintenance.d.ts +173 -0
- package/script/src/secrets/maintenance.d.ts.map +1 -0
- package/script/src/secrets/maintenance.js +323 -0
- package/script/src/secrets/mod.d.ts +6 -0
- package/script/src/secrets/mod.d.ts.map +1 -0
- package/script/src/secrets/mod.js +24 -0
- package/script/src/secrets/secrets.d.ts +192 -0
- package/script/src/secrets/secrets.d.ts.map +1 -0
- package/script/src/secrets/secrets.js +532 -0
- package/skills/loom/SKILL.md +74 -222
- package/skills/loom/references/dependency-upgrades.md +26 -0
- package/skills/loom/references/local-development.md +157 -0
- package/skills/loom/references/release-safety.md +118 -0
- package/skills/loom/references/release-trusted-sources.md +55 -0
- package/skills/loom/references/tools-and-skills.md +83 -0
- package/skills/loom-api-keys/SKILL.md +1 -1
- package/skills/loom-auth/SKILL.md +7 -60
- package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
- package/skills/loom-db/SKILL.md +4 -79
- package/skills/loom-files/SKILL.md +4 -2
- package/skills/loom-files/references/provider-configuration.md +142 -0
- package/skills/loom-jobs/SKILL.md +9 -8
- package/skills/loom-lingui/SKILL.md +5 -3
- package/skills/loom-secrets/SKILL.md +252 -0
- package/skills/loom-torvalds-review/SKILL.md +9 -6
- package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
- 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:
|
|
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
|
-
|
|
24
|
-
|
|
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.
|
|
80
|
-
|
|
81
|
-
|
|
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
|
|
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
|
|
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.
|
|
22
|
-
formatting/lint, typecheck, tests, build, and
|
|
23
|
-
existing warnings and flaky behavior so they
|
|
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
|
-
|
|
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.
|
|
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
|