@gadicc/loom 2.4.0 → 2.5.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/.loom-source-manifest.json +4 -1
- package/esm/src/cli/machineSlots.d.ts +149 -0
- package/esm/src/cli/machineSlots.d.ts.map +1 -0
- package/esm/src/cli/machineSlots.js +417 -0
- package/esm/src/cli/machineSlots.js.map +1 -0
- package/esm/src/cli/machineSlotsCommand.d.ts +24 -0
- package/esm/src/cli/machineSlotsCommand.d.ts.map +1 -0
- package/esm/src/cli/machineSlotsCommand.js +431 -0
- package/esm/src/cli/machineSlotsCommand.js.map +1 -0
- package/esm/src/cli/machineSlotsHost.d.ts +50 -0
- package/esm/src/cli/machineSlotsHost.d.ts.map +1 -0
- package/esm/src/cli/machineSlotsHost.js +192 -0
- package/esm/src/cli/machineSlotsHost.js.map +1 -0
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +39 -1
- package/esm/src/cli/mod.js.map +1 -1
- package/esm/src/cli/testResourceLaunch.d.ts +29 -1
- package/esm/src/cli/testResourceLaunch.d.ts.map +1 -1
- package/esm/src/cli/testResourceLaunch.js +49 -12
- package/esm/src/cli/testResourceLaunch.js.map +1 -1
- package/package.json +2 -2
- package/skills/loom/SKILL.md +43 -15
- package/skills/loom/references/verification-workflow.md +128 -0
- package/source/src/cli/machineSlots.ts +543 -0
- package/source/src/cli/machineSlotsCommand.ts +549 -0
- package/source/src/cli/machineSlotsHost.ts +215 -0
- package/source/src/cli/mod.ts +53 -1
- package/source/src/cli/testResourceLaunch.ts +71 -9
|
@@ -7,7 +7,35 @@ export interface ManagedTestPlan {
|
|
|
7
7
|
warnings: string[];
|
|
8
8
|
}
|
|
9
9
|
/** Combine explicit demand with visible capacity while preserving app caps in-runner. */
|
|
10
|
-
export declare function planManagedTest(report: TestResourceReport, workers: string | undefined, cpuMode?: string): ManagedTestPlan;
|
|
10
|
+
export declare function planManagedTest(report: TestResourceReport, workers: string | undefined, cpuMode?: string, slotGrant?: string): ManagedTestPlan;
|
|
11
|
+
/** Finds an executable on PATH, or throws naming it. */
|
|
12
|
+
export declare function executable(name: string): Promise<string>;
|
|
13
|
+
/** How {@link launch} runs a command beyond its name, arguments and cwd. */
|
|
14
|
+
export interface LaunchOptions {
|
|
15
|
+
/** The child's environment; defaults to this process's. */
|
|
16
|
+
env?: NodeJS.ProcessEnv;
|
|
17
|
+
/**
|
|
18
|
+
* After the child exits, how long to wait for the rest of its own process
|
|
19
|
+
* group (non-terminal runs only) before returning; 0 does not wait.
|
|
20
|
+
*/
|
|
21
|
+
groupGraceMs?: number;
|
|
22
|
+
/** Label for launcher errors on stderr. */
|
|
23
|
+
name?: string;
|
|
24
|
+
/**
|
|
25
|
+
* In a terminal, outlive the job's own Ctrl-C and Ctrl-\: the terminal
|
|
26
|
+
* delivers them to the job, and this process returns only when it exits.
|
|
27
|
+
*/
|
|
28
|
+
holdInterrupts?: boolean;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Runs a command to completion with the launcher's signal rules: without a
|
|
32
|
+
* terminal the child leads its own process group and signals go to the whole
|
|
33
|
+
* group; with one, the terminal's job control already reaches it.
|
|
34
|
+
*/
|
|
35
|
+
export declare function launch(command: string, args: string[], cwd: string, options?: LaunchOptions): Promise<{
|
|
36
|
+
code: number;
|
|
37
|
+
signal?: NodeJS.Signals;
|
|
38
|
+
}>;
|
|
11
39
|
/** Run only the verified finite Vitest adapter; all resource diagnostics use stderr. */
|
|
12
40
|
export declare function runManagedTestCommand(cwd: string, args: string[], options: {
|
|
13
41
|
workers?: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"testResourceLaunch.d.ts","sourceRoot":"","sources":["../../../source/src/cli/testResourceLaunch.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAG/B,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,SAAY,
|
|
1
|
+
{"version":3,"file":"testResourceLaunch.d.ts","sourceRoot":"","sources":["../../../source/src/cli/testResourceLaunch.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAG/B,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,SAAY,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,eAAe,CA0EjB;AAED,wDAAwD;AACxD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAe9D;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,CAAA;CAAE,CAAC,CAoEpD;AAeD,wFAAwF;AACxF,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,EACD,EAAE,EAAE;IAAE,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC/D,OAAO,CAAC,MAAM,CAAC,CA0EjB"}
|
|
@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
|
|
|
8
8
|
import { inspectTestResources, } from "./testResourceHost.js";
|
|
9
9
|
import { managedVitestModuleURL } from "./testVitestRunner.js";
|
|
10
10
|
/** Combine explicit demand with visible capacity while preserving app caps in-runner. */
|
|
11
|
-
export function planManagedTest(report, workers, cpuMode = "inherit") {
|
|
11
|
+
export function planManagedTest(report, workers, cpuMode = "inherit", slotGrant) {
|
|
12
12
|
if ((report.profile === "local" && !workers) ||
|
|
13
13
|
(workers !== undefined &&
|
|
14
14
|
workers !== "auto" &&
|
|
@@ -53,9 +53,15 @@ export function planManagedTest(report, workers, cpuMode = "inherit") {
|
|
|
53
53
|
report.memory.availableBytes <= report.memory.localFloorBytes)) {
|
|
54
54
|
throw new Error("Local memory headroom is unavailable or below the desktop floor (exit 121)");
|
|
55
55
|
}
|
|
56
|
+
// Inside a machine-slots grant (docs/machine-slots.md) the grant is the
|
|
57
|
+
// capacity; pinning already narrows the inherited CPUs to it.
|
|
58
|
+
const slots = /^\d+$/.test(slotGrant ?? "") ? Number(slotGrant) : 0;
|
|
59
|
+
if (report.profile === "local" && slots >= 1)
|
|
60
|
+
ceiling = Math.min(ceiling, slots);
|
|
56
61
|
return { workers: ceiling, cpus, epoch: selection?.epoch ?? null, warnings };
|
|
57
62
|
}
|
|
58
|
-
|
|
63
|
+
/** Finds an executable on PATH, or throws naming it. */
|
|
64
|
+
export async function executable(name) {
|
|
59
65
|
for (const directory of (process.env.PATH ?? "").split(delimiter)) {
|
|
60
66
|
if (!directory)
|
|
61
67
|
continue;
|
|
@@ -70,14 +76,19 @@ async function executable(name) {
|
|
|
70
76
|
}
|
|
71
77
|
throw new Error(`Required executable ${name} is unavailable`);
|
|
72
78
|
}
|
|
73
|
-
|
|
79
|
+
/**
|
|
80
|
+
* Runs a command to completion with the launcher's signal rules: without a
|
|
81
|
+
* terminal the child leads its own process group and signals go to the whole
|
|
82
|
+
* group; with one, the terminal's job control already reaches it.
|
|
83
|
+
*/
|
|
84
|
+
export function launch(command, args, cwd, options = {}) {
|
|
74
85
|
return new Promise((done) => {
|
|
75
86
|
const foreground = process.platform !== "win32" &&
|
|
76
87
|
Boolean(process.stdin.isTTY || process.stdout.isTTY || process.stderr.isTTY);
|
|
77
88
|
const grouped = process.platform !== "win32" && !foreground;
|
|
78
89
|
const child = spawn(command, args, {
|
|
79
90
|
cwd,
|
|
80
|
-
env: process.env,
|
|
91
|
+
env: options.env ?? process.env,
|
|
81
92
|
stdio: "inherit",
|
|
82
93
|
detached: grouped,
|
|
83
94
|
});
|
|
@@ -85,6 +96,11 @@ function launch(command, args, cwd) {
|
|
|
85
96
|
const signals = foreground
|
|
86
97
|
? ["SIGTERM", "SIGHUP"]
|
|
87
98
|
: ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
|
|
99
|
+
// The terminal already sent these to the job; only wait for it.
|
|
100
|
+
const held = foreground && options.holdInterrupts ? ["SIGINT", "SIGQUIT"] : [];
|
|
101
|
+
const ignore = () => { };
|
|
102
|
+
for (const signal of held)
|
|
103
|
+
process.on(signal, ignore);
|
|
88
104
|
let receivedSignal;
|
|
89
105
|
const handlers = signals.map((signal) => {
|
|
90
106
|
const handler = () => {
|
|
@@ -110,20 +126,41 @@ function launch(command, args, cwd) {
|
|
|
110
126
|
settled = true;
|
|
111
127
|
for (const item of handlers)
|
|
112
128
|
process.off(item.signal, item.handler);
|
|
129
|
+
for (const signal of held)
|
|
130
|
+
process.off(signal, ignore);
|
|
113
131
|
done(value);
|
|
114
132
|
};
|
|
115
133
|
child.once("error", (error) => {
|
|
116
|
-
console.error(
|
|
134
|
+
console.error(`${options.name ?? "Loom test launcher"}: ${error.message}`);
|
|
117
135
|
finish({ code: 120 });
|
|
118
136
|
});
|
|
119
|
-
child.once("close", (code, signal) =>
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
137
|
+
child.once("close", (code, signal) => {
|
|
138
|
+
const result = {
|
|
139
|
+
code: code ?? 1,
|
|
140
|
+
...((receivedSignal ?? signal)
|
|
141
|
+
? { signal: receivedSignal ?? signal ?? undefined }
|
|
142
|
+
: {}),
|
|
143
|
+
};
|
|
144
|
+
if (grouped && child.pid && options.groupGraceMs)
|
|
145
|
+
void groupEmpty(child.pid, options.groupGraceMs).then(() => finish(result));
|
|
146
|
+
else
|
|
147
|
+
finish(result);
|
|
148
|
+
});
|
|
125
149
|
});
|
|
126
150
|
}
|
|
151
|
+
/** Waits until no process is left in a group, or the grace runs out. */
|
|
152
|
+
async function groupEmpty(pgid, graceMs) {
|
|
153
|
+
const until = Date.now() + graceMs;
|
|
154
|
+
while (Date.now() < until) {
|
|
155
|
+
try {
|
|
156
|
+
process.kill(-pgid, 0);
|
|
157
|
+
}
|
|
158
|
+
catch {
|
|
159
|
+
return;
|
|
160
|
+
}
|
|
161
|
+
await new Promise((resolve) => setTimeout(resolve, 100));
|
|
162
|
+
}
|
|
163
|
+
}
|
|
127
164
|
/** Run only the verified finite Vitest adapter; all resource diagnostics use stderr. */
|
|
128
165
|
export async function runManagedTestCommand(cwd, args, options, io) {
|
|
129
166
|
if (args[0] !== "vitest" || args[1] !== "run") {
|
|
@@ -142,7 +179,7 @@ export async function runManagedTestCommand(cwd, args, options, io) {
|
|
|
142
179
|
let taskset;
|
|
143
180
|
try {
|
|
144
181
|
report = await inspectTestResources({ profile: options.profile });
|
|
145
|
-
plan = planManagedTest(report, options.workers, options.cpuMode);
|
|
182
|
+
plan = planManagedTest(report, options.workers, options.cpuMode, process.env.LOOM_SLOTS);
|
|
146
183
|
node = await executable("node");
|
|
147
184
|
if (plan.cpus)
|
|
148
185
|
taskset = await executable("taskset");
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"testResourceLaunch.js","sourceRoot":"","sources":["../../../source/src/cli/testResourceLaunch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,oBAAoB,GAErB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAU/D,yFAAyF;AACzF,MAAM,UAAU,eAAe,CAC7B,MAA0B,EAC1B,OAA2B,EAC3B,OAAO,GAAG,SAAS;
|
|
1
|
+
{"version":3,"file":"testResourceLaunch.js","sourceRoot":"","sources":["../../../source/src/cli/testResourceLaunch.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gadicc/loom",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.5.0",
|
|
4
4
|
"description": "Shared helpers and verification tooling for Next.js applications.",
|
|
5
5
|
"homepage": "https://github.com/gadicc/loom#readme",
|
|
6
6
|
"repository": {
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"url": "https://github.com/gadicc/loom/issues"
|
|
12
12
|
},
|
|
13
13
|
"loom": {
|
|
14
|
-
"gitCommit": "
|
|
14
|
+
"gitCommit": "210d717b1e3b24e4cf8002382fda32f728b25372"
|
|
15
15
|
},
|
|
16
16
|
"type": "module",
|
|
17
17
|
"main": "./esm/mod.js",
|
package/skills/loom/SKILL.md
CHANGED
|
@@ -204,18 +204,36 @@ as more authoritative than a generic mapped error when deciding what failed.
|
|
|
204
204
|
a tradeoff.
|
|
205
205
|
- Do not add comments for obvious assignments or control flow.
|
|
206
206
|
|
|
207
|
-
## Verification
|
|
208
|
-
|
|
209
|
-
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
207
|
+
## Verification and working branches
|
|
208
|
+
|
|
209
|
+
- Default to an isolated topic branch and worktree for code changes. Direct work
|
|
210
|
+
on the default/protected branch needs explicit user authorization naming that
|
|
211
|
+
branch (a generic "commit this" does not) and an independently owned checkout
|
|
212
|
+
with no unrelated or user-owned changes; never switch a shared checkout.
|
|
213
|
+
- Intermediate commits on isolated branches need passing affected tests and
|
|
214
|
+
relevant type, lint, translation and feature checks. Record what ran and which
|
|
215
|
+
full/final gates are pending; these checkpoints are not merge-ready evidence.
|
|
216
|
+
- Before declaring a code-changing feature complete or ready for review/merge,
|
|
217
|
+
pass the full local suite and required quality/build/runtime gates on the final
|
|
218
|
+
candidate. Verify the actual merge candidate if the target branch has moved.
|
|
219
|
+
In the Loom repository use its recorded full gates; consumers use
|
|
220
|
+
`project.tooling`.
|
|
221
|
+
- Before every direct default/protected-branch commit, pass the full suite and
|
|
222
|
+
required gates for that exact commit, including direct prose-only commits.
|
|
223
|
+
User authorization for Main work does not waive verification. Agent-performed
|
|
224
|
+
local merges, squashes, fast-forwards, cherry-picks and rebases onto that branch
|
|
225
|
+
require the same authorization and full verification of the resulting tree.
|
|
226
|
+
- Broaden checks earlier for shared contracts, generated output, tooling,
|
|
227
|
+
authentication, persistence or uncertain impact. Choose coherent feature
|
|
228
|
+
checkpoints rather than repeated full runs for unused microsteps.
|
|
229
|
+
- Format first. Reuse evidence only while its tested inputs and relevant
|
|
230
|
+
environment remain unchanged. Later code edits invalidate a prior final/full
|
|
231
|
+
result. Compare staged and working content; use an isolated snapshot when
|
|
232
|
+
user-owned changes differ, without stashing or resetting them.
|
|
233
|
+
- Read [verification workflow](references/verification-workflow.md) when choosing
|
|
234
|
+
branch/Main checkpoints, sharing incomplete work, reusing final evidence or
|
|
235
|
+
reducing test cost. It distinguishes deferred full checks from failing checks
|
|
236
|
+
and preserves the existing database test tiers.
|
|
219
237
|
- Ordinary prose changes need formatting and reference checks. Packaged skills,
|
|
220
238
|
catalog metadata, activation logic, and reference moves also need relevant
|
|
221
239
|
skill/catalog tests and verification that references ship and resolve.
|
|
@@ -226,9 +244,8 @@ as more authoritative than a generic mapped error when deciding what failed.
|
|
|
226
244
|
integrity. Recommendations are optional; checking does not authorize adoption.
|
|
227
245
|
- Use runtime verification for affected Next.js behavior when a server is
|
|
228
246
|
running. Keep required build, browser-type, integration, CI and release gates
|
|
229
|
-
intact. In Loom, `bun run check`
|
|
230
|
-
|
|
231
|
-
Oxc quality plus Deno parity; use `bun run format` for formatting/import order
|
|
247
|
+
intact. In the Loom repository, `bun run check` is the full gate described in
|
|
248
|
+
the linked workflow; use `bun run format` for formatting/import order
|
|
232
249
|
and explicit `bun run lint:fix` for safe lint fixes. Never put suggestion or
|
|
233
250
|
dangerous lint fixes in format/save/CI. Consumer tools remain independently
|
|
234
251
|
recorded.
|
|
@@ -236,6 +253,17 @@ as more authoritative than a generic mapped error when deciding what failed.
|
|
|
236
253
|
guidance overlaps. Use feature-specific Loom skills for affected active
|
|
237
254
|
features.
|
|
238
255
|
|
|
256
|
+
## Heavy local work
|
|
257
|
+
|
|
258
|
+
On a shared Linux workstation, heavy steps (Vitest suites, `next build`)
|
|
259
|
+
from every Loom consumer draw CPUs from one machine-wide pool. Where the app
|
|
260
|
+
wraps its heavy tasks with `loom slots run`, run those tasks as recorded; do
|
|
261
|
+
not bypass the wrapper, and never add `--allow-unpooled` on your own. A task
|
|
262
|
+
that waits is queued behind other work: `loom slots status` shows who holds
|
|
263
|
+
the CPUs and who is ahead. Configs read `LOOM_SLOTS` for their worker counts
|
|
264
|
+
(Vitest `maxWorkers`, Next `experimental.cpus`). See `docs/machine-slots.md`
|
|
265
|
+
in the Loom repository.
|
|
266
|
+
|
|
239
267
|
## Local development
|
|
240
268
|
|
|
241
269
|
Use `loom dev local <path>` and `loom dev sync` for unpublished package work.
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# Verification checkpoints and working branches
|
|
2
|
+
|
|
3
|
+
Use this workflow in Loom and consuming applications. The repository's stronger
|
|
4
|
+
required checks and explicit user instructions take precedence. This guidance
|
|
5
|
+
changes when verification is required; it does not remove tests or lower coverage.
|
|
6
|
+
|
|
7
|
+
## Choose an isolated working context
|
|
8
|
+
|
|
9
|
+
Use a topic branch and worktree for code changes by default, especially multi-step
|
|
10
|
+
features, migrations, shared contracts, parallel work or an already dirty checkout.
|
|
11
|
+
Inspect status and applicable instructions first. Base the worktree on the intended
|
|
12
|
+
integration revision and preserve unrelated changes in other checkouts.
|
|
13
|
+
|
|
14
|
+
Direct work on the default/protected branch (often `main` or `master`) needs
|
|
15
|
+
explicit user authorization and an independently owned checkout with no unrelated
|
|
16
|
+
or user-owned changes. Honor relevant standing or session authorization without
|
|
17
|
+
asking again. Do not infer permission from a clean status, a small patch or unrelated task approval.
|
|
18
|
+
A request to fix, commit or finish a task authorizes commits on the isolated
|
|
19
|
+
branch, not the default branch. Main authorization must name the default/protected
|
|
20
|
+
branch or come from a standing user/owner instruction covering it; agent-written
|
|
21
|
+
notes, feature records and PR text are not authorization.
|
|
22
|
+
Every direct commit there requires full verification, including prose-only commits.
|
|
23
|
+
If that cost is disproportionate, use a topic branch integrated through the
|
|
24
|
+
project's reviewed path instead.
|
|
25
|
+
|
|
26
|
+
An agent-performed local merge, squash, fast-forward, cherry-pick or rebase onto
|
|
27
|
+
the default/protected branch is direct default-branch work: it needs the same
|
|
28
|
+
authorization and full gates on the resulting tree. The Merge row below covers
|
|
29
|
+
integration through the project's reviewed path, for example a PR whose required
|
|
30
|
+
checks ran on the merge candidate.
|
|
31
|
+
|
|
32
|
+
Do not copy another checkout's credentials or env files to make a worktree
|
|
33
|
+
runnable. Use the project's documented per-worktree environment mechanism and
|
|
34
|
+
recorded dependency-install tooling.
|
|
35
|
+
|
|
36
|
+
Creating a branch/worktree grants no additional permission to push, merge, publish,
|
|
37
|
+
deploy, migrate a live database or message another person. Follow existing task
|
|
38
|
+
scope and authorization for those actions.
|
|
39
|
+
|
|
40
|
+
## Match the checkpoint to the evidence
|
|
41
|
+
|
|
42
|
+
| Checkpoint | Required evidence |
|
|
43
|
+
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
44
|
+
| During implementation | Affected tests and relevant checks while editing |
|
|
45
|
+
| Intermediate isolated-branch commit | Passing affected tests, relevant type/lint/translation/feature checks; full/final gates explicitly pending |
|
|
46
|
+
| Code-changing feature complete or ready for review/merge | Full local suite and repository-required quality/build/runtime gates on the final candidate |
|
|
47
|
+
| Merge to a default/protected branch | Required checks pass for the actual merge candidate; verify the resulting tree when the target moves, unless integration fast-forwards to exactly the tested tree |
|
|
48
|
+
| Direct default/protected-branch commit | Full local suite and required gates on the exact committed content, even for prose |
|
|
49
|
+
| Ordinary prose-only work on a topic branch | Formatting and reference checks; packaged skills/catalog/activation changes also need their relevant tests and package/link checks |
|
|
50
|
+
|
|
51
|
+
Use recorded tooling. Consumers use their authoritative `project.tooling` tasks.
|
|
52
|
+
|
|
53
|
+
Loom's full final gate is `bun run check`: it runs Oxc quality, Bun production
|
|
54
|
+
types/tests, isolated DB/resource fixture contracts, machine-slots contracts
|
|
55
|
+
(`test:slots`), and `deno task check:parity`
|
|
56
|
+
(Deno tests, DB/resource fixtures, browser types and package build). A successful
|
|
57
|
+
run already includes that parity sequence; running `deno task check` afterward
|
|
58
|
+
would duplicate it. `deno task check` alone omits the Bun production/type gates.
|
|
59
|
+
Preserve stronger coverage, integration, native database, bundler, browser, release
|
|
60
|
+
and CI gates. A filtered command returning success proves only its selected scope.
|
|
61
|
+
|
|
62
|
+
Broaden verification earlier when auth, persistence, compiler/format compatibility,
|
|
63
|
+
shared APIs, generated output or uncertain dependencies make local impact hard to
|
|
64
|
+
bound. Do not wait for final review to discover that a new boundary breaks another
|
|
65
|
+
consumer. This is a judgment about impact, not a requirement for a full run after
|
|
66
|
+
every small implementation step.
|
|
67
|
+
|
|
68
|
+
Choose checkpoints around coherent behavior and its tests. An unused helper need
|
|
69
|
+
not become a separate commit/full-verification cycle merely because it was written
|
|
70
|
+
first. Intermediate branch commits may be useful recovery/review checkpoints;
|
|
71
|
+
they do not require declaring a feature complete.
|
|
72
|
+
|
|
73
|
+
## Record what is known
|
|
74
|
+
|
|
75
|
+
For an intermediate checkpoint, record the relevant commands and outcomes and
|
|
76
|
+
state that the full suite/final gates are pending. Do not mark a shared PR ready
|
|
77
|
+
until its completion gates pass. Do not describe a branch checkpoint as fully verified,
|
|
78
|
+
merge-ready or production-ready just because its affected tests pass.
|
|
79
|
+
|
|
80
|
+
"Pending" means not yet run on this candidate; an observed or known failure is
|
|
81
|
+
reported as failing. A recovery checkpoint with failing affected tests needs
|
|
82
|
+
user agreement and that label. A deferred full suite is different from a failing
|
|
83
|
+
required check. Fix failures caused by the change. Disclose known failures and obtain user agreement before
|
|
84
|
+
making an exception to a required gate; never silently skip, weaken assertions,
|
|
85
|
+
raise timeouts, lower thresholds or declare a failing candidate complete.
|
|
86
|
+
|
|
87
|
+
Squash merging is one option when the project wants a fully verified Main
|
|
88
|
+
history while retaining cheap development checkpoints. A merge commit can verify
|
|
89
|
+
its resulting tree, but it does not make every intermediate branch commit fully
|
|
90
|
+
verified or guarantee they all pass a later bisect. Follow the project's chosen
|
|
91
|
+
history policy; this guidance does not authorize a history rewrite.
|
|
92
|
+
|
|
93
|
+
## Reuse evidence for the tree actually being committed
|
|
94
|
+
|
|
95
|
+
Format before final gates. Reuse results only while tested source/configuration,
|
|
96
|
+
generated inputs, dependencies and relevant environment remain unchanged. Later
|
|
97
|
+
code changes or modifying hooks invalidate earlier full/final results. Re-run the
|
|
98
|
+
necessary final gates on the final candidate rather than citing an earlier green
|
|
99
|
+
commit. Ordinary prose means documentation neither shipped nor parsed by
|
|
100
|
+
tools/tests; features.yaml, catalogs and packaged skills are inputs. "Explicitly excluded"
|
|
101
|
+
means excluded by the recorded tooling configuration, not an agent's ad-hoc
|
|
102
|
+
choice. Behavior-affecting packaged guidance uses the feature-completion gate.
|
|
103
|
+
|
|
104
|
+
Compare the index and working content; do not rely on an unstaged fix making tests
|
|
105
|
+
pass. If user-owned changes differ, verify an isolated snapshot of the intended
|
|
106
|
+
commit instead of stashing/resetting those changes. Check the intended base and
|
|
107
|
+
final merge result when integrating, and keep independent repositories' evidence
|
|
108
|
+
and commits separate. Cite CI only when it checked the candidate being merged/
|
|
109
|
+
released. If the target moved, the tested tree is stale unless integration
|
|
110
|
+
fast-forwards to exactly that tree; verify the merge result in an isolated
|
|
111
|
+
worktree or rely on CI that tested it. Updating a shared branch by rebase still
|
|
112
|
+
needs history-rewrite authorization.
|
|
113
|
+
|
|
114
|
+
## Reduce test cost at the correct boundary
|
|
115
|
+
|
|
116
|
+
Use the existing [database test-boundary guidance](../../loom-db/references/test-boundaries.md).
|
|
117
|
+
Plain decisions and orchestration do not all need a database engine; real SQL,
|
|
118
|
+
transactions, constraints and concurrency still need the appropriate backend.
|
|
119
|
+
Preserve production-loader coverage and use discriminating query faults when
|
|
120
|
+
separating a previously database-heavy test. A fake passing on its own is not SQL
|
|
121
|
+
or provider evidence.
|
|
122
|
+
|
|
123
|
+
For worker counts, setup/import/schema cost, caching and isolation experiments,
|
|
124
|
+
follow that existing reference and its recorded evidence before changing tooling.
|
|
125
|
+
|
|
126
|
+
Native browser/provider claims need native evidence, not only parser or DOM
|
|
127
|
+
simulations. Put app-specific contracts near their owning modules and route
|
|
128
|
+
agents there from local instructions.
|