@outerlayer/cli 0.40.0-next.20261116130619 → 0.40.0-next.20261116135746
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/dist/build-info.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"id":"2026-11-
|
|
1
|
+
{"id":"2026-11-16T14:06:30.442Z","root":"/home/runner/work/outerlayer/outerlayer","pkg":"outerlayer"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@outerlayer/cli",
|
|
3
|
-
"version": "0.40.0-next.
|
|
3
|
+
"version": "0.40.0-next.20261116135746",
|
|
4
4
|
"description": "OuterLayer CLI — commands: setup, init, claude, opencode, codex, connect, doctor, login, logout, sync, daemon (alias: watch), emit, demo, findings, work, run, spec, runner, hooks, mcp, context. Capture and sync coding-agent sessions, and record proof of factory work.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Magu Studios, Inc.",
|
|
@@ -340,6 +340,14 @@ Run them in order.
|
|
|
340
340
|
repository's own pre-push checks and tests pass on the branch. A branch
|
|
341
341
|
that cannot go green escalates.
|
|
342
342
|
|
|
343
|
+
The implementer writes the test of every declared proof in this phase,
|
|
344
|
+
beside the feature and before the gate. A criterion that declares
|
|
345
|
+
`proof: video` or `proof: screenshot` gets a chapter of the item's demo
|
|
346
|
+
test, named by its id. A repository's gate can refuse a push without that
|
|
347
|
+
chapter. The demo test is code: write it even when the app does not start
|
|
348
|
+
here. A later phase can run it again. A proof with no test can never be
|
|
349
|
+
recorded.
|
|
350
|
+
|
|
343
351
|
The implementer runs on the Implementing model setting. Default: the model
|
|
344
352
|
the session runs on.
|
|
345
353
|
|
|
@@ -372,9 +380,10 @@ Run them in order.
|
|
|
372
380
|
finds on the pull request.
|
|
373
381
|
5. **Evidence.** Run `outerlayer emit step "Evidence" --item "$OUTERLAYER_WORK"`,
|
|
374
382
|
then apply the team's changes for this phase. Read [references/evidence.md](references/evidence.md)
|
|
375
|
-
when the pull request opens, and run it.
|
|
376
|
-
|
|
377
|
-
|
|
383
|
+
when the pull request opens, and run it. This phase runs the proof tests
|
|
384
|
+
the Implement phase committed, and fixes each one that fails. It does not
|
|
385
|
+
write a missing demo test from the start: a declared proof with no test is
|
|
386
|
+
an Implement fault, and the implementer writes it. In a
|
|
378
387
|
runner build, check each proof with `outerlayer work proofs --check`, and
|
|
379
388
|
record none: the host records them at the pushed head. In a local session,
|
|
380
389
|
record each proof with `outerlayer work proofs --record` after the last
|
|
@@ -399,18 +408,25 @@ is "The tests need STRIPE_KEY. Add it as a build variable." Keep it under 200
|
|
|
399
408
|
characters. The Work page and the Overview tab show your sentence as the reason
|
|
400
409
|
the item needs attention. Skip it when the build opens a pull request.
|
|
401
410
|
|
|
411
|
+
Only one kind of proof can stay unproven: a proof this host cannot produce.
|
|
412
|
+
It needs something the host does not have, such as macOS, Windows, a
|
|
413
|
+
physical device or a real third-party account. `build-reports/evidence.md`
|
|
414
|
+
names each such proof and what it needs. Its test is still committed when a
|
|
415
|
+
test can record it. A written reason excuses no other proof. A database,
|
|
416
|
+
app or browser that does not start is a fault to fix, never such a reason.
|
|
417
|
+
|
|
402
418
|
In a runner build, end the run only when `outerlayer work proofs --check`
|
|
403
|
-
exits 0 at the last commit,
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
419
|
+
exits 0 at the last commit, apart from proofs this host cannot produce. Do
|
|
420
|
+
not run `--record`: the host records each proof at the pushed head. A proof
|
|
421
|
+
that fails the check, or a row marked `failed`, needs a fix: add or change
|
|
422
|
+
the test that proves the criterion, commit, and check again. A proof that
|
|
423
|
+
still fails after the takeover in state rule 2 escalates. The final report
|
|
424
|
+
names it as failed, never as excused.
|
|
408
425
|
|
|
409
426
|
In a local session, run the release command below last, after the pull request is open and the
|
|
410
427
|
evidence is emitted, and run no other tool call after it. Before it, run `outerlayer sync` and then
|
|
411
428
|
`outerlayer work proofs --item "$OUTERLAYER_WORK"`. End the run only when it
|
|
412
|
-
exits 0,
|
|
413
|
-
and the reason. A proof out of date because of a later commit needs
|
|
429
|
+
exits 0, apart from proofs this host cannot produce. A proof out of date because of a later commit needs
|
|
414
430
|
`outerlayer work proofs --record` at the final commit, not a reason. A row marked `failed` has no such excuse: add or change a test that
|
|
415
431
|
proves the criterion, and run the command again. Exit 2 means it could not
|
|
416
432
|
decide: fix the reason it prints and run it again:
|
|
@@ -112,6 +112,41 @@ report. When the build drafted the criteria from the issue's description, they
|
|
|
112
112
|
are requirements in the same way. When no criteria were recorded, write tests
|
|
113
113
|
from the description in the same order.
|
|
114
114
|
|
|
115
|
+
Write the test of every declared proof in this phase, in the same commits as
|
|
116
|
+
the feature and before the gate. The Evidence phase runs these tests and
|
|
117
|
+
fixes what fails. It does not write them.
|
|
118
|
+
|
|
119
|
+
- A criterion that declares `proof: video` or `proof: screenshot` gets a
|
|
120
|
+
chapter of the item's demo test. The demo test is a Playwright test named
|
|
121
|
+
`*.demo.spec.ts`. Put it where the repository keeps its Playwright tests, in
|
|
122
|
+
the folder the instructions name, else in `e2e/demo/`. It uses
|
|
123
|
+
`@outerlayer/playwright`, as the outerlayer-evidence skill's "Record a demo"
|
|
124
|
+
says. Open each chapter with the id of its criterion, for example
|
|
125
|
+
`demo.chapter("AC-7-02", "<title>", async () => { ... })`. Keep the chapters
|
|
126
|
+
in the criteria's order. A screenshot criterion's chapter calls
|
|
127
|
+
`demo.screenshot()` after the `expect` that shows the result.
|
|
128
|
+
- Tell each chapter in beats with `demo.say()`. Sign in once, and seed and
|
|
129
|
+
wait between beats, so the demo shows only narrated steps. In each beat,
|
|
130
|
+
check first with `expect(locator)` the element its line names, so the
|
|
131
|
+
recorder rings it. Write each line as you would say it to a teammate at
|
|
132
|
+
your screen, in plain words. If the repository's CI cannot start the app,
|
|
133
|
+
mark the file so that CI skips it.
|
|
134
|
+
- A `// proves` comment on a unit or jsdom test records no video or
|
|
135
|
+
screenshot. Only a demo chapter does.
|
|
136
|
+
- Write the demo test even when the app does not start here. It is code, like
|
|
137
|
+
the feature. When the app starts, run the demo test once before the gate.
|
|
138
|
+
When it does not, quote the command and its error in your report.
|
|
139
|
+
- A report, log or file proof is a test, in any language, that writes
|
|
140
|
+
`$OUTERLAYER_PROOF_OUT/<criterion id>.<ext>`. The kind of the file must be
|
|
141
|
+
the kind the criterion declares. The test writes outside the repository, so
|
|
142
|
+
there is nothing to ignore or commit.
|
|
143
|
+
- The repository has one `.outerlayer-proofs.yaml` at its root. When it is
|
|
144
|
+
missing, write it and commit it. `setup` lists the commands that seed and
|
|
145
|
+
start the app. Each setup command must return once the app is ready.
|
|
146
|
+
`teardown` lists the commands that stop it. Each entry in `runners` has a
|
|
147
|
+
`files` glob of test files and a `command` that runs them, with `{files}`
|
|
148
|
+
where the matched files go.
|
|
149
|
+
|
|
115
150
|
Version any new database migration with the current UTC time, never a round or
|
|
116
151
|
guessed one. Two open branches that guess the same time both pass their own
|
|
117
152
|
checks, and the second to merge breaks the build for everyone.
|
|
@@ -201,53 +236,34 @@ The shared rules apply, and the outerlayer-evidence skill governs the emit
|
|
|
201
236
|
mechanics. Your inputs are the issue, the pull request number, the criteria
|
|
202
237
|
that declare a proof form, and the instructions-file pointer.
|
|
203
238
|
|
|
239
|
+
The Implement phase committed the test of every declared proof: a chapter of
|
|
240
|
+
the item's demo test for each video or screenshot criterion, and a test that
|
|
241
|
+
writes each report, log or file proof. Your work is to run those tests, look
|
|
242
|
+
at what they record, and fix what fails. Do not write a missing demo test from
|
|
243
|
+
the start. When a criterion that declares a proof form has no test, name it in
|
|
244
|
+
your report as an Implement fault, and go on with the others. The orchestrator
|
|
245
|
+
sends it back to the implementer.
|
|
246
|
+
|
|
204
247
|
Run the app and drive the feature by hand. A screenshot or video is taken in a
|
|
205
248
|
real browser against the running application, reached through its own routes
|
|
206
249
|
by a signed-in user, inside its real shell and theme. Never capture a test
|
|
207
250
|
render, a jsdom dump or a standalone file of a component. It shows neither what
|
|
208
251
|
a user sees nor that the page works. Seed what the page needs through the
|
|
209
|
-
application's own paths. When a state cannot be reached that way, the
|
|
210
|
-
|
|
252
|
+
application's own paths. When a state cannot be reached that way, change the
|
|
253
|
+
demo test so it seeds through those paths. Before you go on, look at each
|
|
211
254
|
capture: it shows the application's navigation and real rows.
|
|
212
255
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
folder the instructions name, else in `e2e/demo/`. Name it `*.demo.spec.ts`.
|
|
216
|
-
Commit it in the pull request. The demo record names this test, so an amend
|
|
217
|
-
can run it again at a new head. If the repository's CI cannot start the app,
|
|
218
|
-
mark the file so that CI skips it.
|
|
219
|
-
|
|
220
|
-
Record each criterion that declares `proof: screenshot` as a chapter of the same
|
|
221
|
-
demo, with a `demo.screenshot()` call where the result shows. The frame then
|
|
222
|
-
comes from the committed test, so a later session records it again at the new head.
|
|
223
|
-
|
|
224
|
-
Every proof comes from a test that you commit with the change. The test uses
|
|
225
|
-
the id of the criterion it proves where it records the proof, for example
|
|
256
|
+
Every proof comes from a test committed with the change. The test uses the id
|
|
257
|
+
of the criterion it proves where it records the proof, for example
|
|
226
258
|
`demo.chapter("AC-7-02", ...)` or the file `<criterion id>.log` it writes.
|
|
227
259
|
`outerlayer work proofs --record` finds the tests at HEAD that hold the id of
|
|
228
|
-
each proof that is not current, and runs them.
|
|
260
|
+
each proof that is not current, and runs them. The demo record names the demo
|
|
261
|
+
test, so an amend can run it again at a new head.
|
|
229
262
|
|
|
230
|
-
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
test files and a `command` that runs them, with `{files}` where the matched
|
|
235
|
-
files go.
|
|
236
|
-
- A demo test uses `@outerlayer/playwright`, one chapter for each screenshot or
|
|
237
|
-
video criterion in the criteria's order, as the outerlayer-evidence skill's
|
|
238
|
-
"Record a demo" says. Tell each chapter in beats with `demo.say()`: sign in
|
|
239
|
-
once, and seed and wait between beats, so the demo shows only narrated
|
|
240
|
-
steps. In each beat, check first with `expect(locator)` the element its
|
|
241
|
-
line names, so the recorder rings it. Write each line as you would say it to a
|
|
242
|
-
teammate at your screen, in plain words. Render it with `outerlayer emit
|
|
243
|
-
demo <manifest> --output demo.webm`, then watch and listen to it before
|
|
244
|
-
you commit the test. Each beat rings what its line names. Write again each
|
|
245
|
-
line that sounds read off a spec or like an advert. The fixture writes the
|
|
246
|
-
manifest where `OUTERLAYER_PROOF_OUT` names.
|
|
247
|
-
- A report, log or file proof is a test, in any language, that writes
|
|
248
|
-
`$OUTERLAYER_PROOF_OUT/<criterion id>.<ext>`. The kind of the file must be the
|
|
249
|
-
kind the criterion declares. The test writes outside the repository, so there is
|
|
250
|
-
nothing to ignore or commit.
|
|
263
|
+
- Render the demo with `outerlayer emit demo <manifest> --output demo.webm`.
|
|
264
|
+
The fixture writes the manifest where `OUTERLAYER_PROOF_OUT` names. Watch
|
|
265
|
+
and listen to it. Each beat rings what its line names. Write again each line
|
|
266
|
+
that sounds read off a spec or like an advert, and commit the change.
|
|
251
267
|
- A `test` proof is a JUnit XML file of test results, bound to the criterion.
|
|
252
268
|
Record it yourself the first time, unless the policy file sets
|
|
253
269
|
`criteria.test_proof: ci`. CI then records it. Run the repository's test
|
|
@@ -270,23 +286,25 @@ each proof that is not current, and runs them.
|
|
|
270
286
|
- files: "apps/api/src/test/java/**/*Test.java"
|
|
271
287
|
command: 'cd apps/api && ./mvnw -q test -Dtest="$(for f in {files}; do basename "$f" .java; done | paste -sd, -)"'
|
|
272
288
|
```
|
|
273
|
-
- A proof
|
|
289
|
+
- A proof this host cannot produce is the one proof that can stay unproven.
|
|
290
|
+
It needs something the host does not have, such as macOS, Windows, a
|
|
291
|
+
physical device or a real third-party account. Name what it needs in
|
|
274
292
|
`build-reports/evidence.md`.
|
|
275
293
|
- A setup command that fails is a fault to fix. Examples are a database, an
|
|
276
|
-
app or a browser that does not start. It is not a proof
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
294
|
+
app or a browser that does not start. It is not a proof this host cannot
|
|
295
|
+
produce. Read the error and fix the cause. If you cannot, quote the command
|
|
296
|
+
and its error in `build-reports/evidence.md`. The proof stays failed, and
|
|
297
|
+
the final report names it as failed, not as excused.
|
|
298
|
+
|
|
299
|
+
Commit every fix. In a runner build (`OUTERLAYER_JOB_DIR` is set), run
|
|
300
|
+
`outerlayer work proofs --check` from the committed checkout. In a local
|
|
301
|
+
session, run `outerlayer work proofs --record`. Each stops when a tracked file
|
|
302
|
+
differs from HEAD, and runs only what is committed at HEAD. Each skips a proof
|
|
303
|
+
that is current. `--record` emits each proof at HEAD. `--check` emits nothing,
|
|
304
|
+
because the host records each proof at the pushed head. Never emit by hand a
|
|
305
|
+
proof that a test can make, except a `test` proof the first time, as above.
|
|
306
|
+
Always pass `--pr <number>` when the item links more than one pull request in
|
|
307
|
+
the repository.
|
|
290
308
|
|
|
291
309
|
The output names each proof that failed or is still not current, with the
|
|
292
310
|
reason. Fix that test, commit it and run the same command again. Do not run it
|
|
@@ -295,6 +313,7 @@ orchestrator runs it once more, at the run's last head.
|
|
|
295
313
|
|
|
296
314
|
Run `outerlayer sync`, then `outerlayer work proofs --item "$OUTERLAYER_WORK"`.
|
|
297
315
|
|
|
298
|
-
Write `build-reports/evidence.md` naming every criterion with its artifact
|
|
299
|
-
|
|
300
|
-
|
|
316
|
+
Write `build-reports/evidence.md` naming every criterion with its artifact or
|
|
317
|
+
check result. Name each criterion with no test, each proof that still fails
|
|
318
|
+
with its error, and each proof this host cannot produce with what it needs. A
|
|
319
|
+
criterion you could not evidence is a result, not a gap to leave silent.
|
|
@@ -15,17 +15,22 @@ the issue, the pull request number, the criteria that declare a proof form, the
|
|
|
15
15
|
instructions-file pointer and the outerlayer-evidence skill.
|
|
16
16
|
|
|
17
17
|
A criterion that declares `proof: screenshot` needs a screenshot bound to its
|
|
18
|
-
id
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
item's one demo. A screenshot never satisfies `proof: video`. A criterion
|
|
22
|
-
passing test results at the head commit. A
|
|
18
|
+
id: a chapter of the item's demo, with a `demo.screenshot()` call. The
|
|
19
|
+
evidence agent emits a screenshot with `emit artifact` only for a state no demo
|
|
20
|
+
test can reach. One that declares `proof: video` needs a video: its chapter of
|
|
21
|
+
the item's one demo. A screenshot never satisfies `proof: video`. A criterion
|
|
22
|
+
that declares `proof: test` needs passing test results at the head commit. A
|
|
23
|
+
criterion with `proof: null` is one a person proves, and needs no artifact.
|
|
23
24
|
|
|
24
|
-
The
|
|
25
|
-
|
|
26
|
-
finds those tests at HEAD, runs them through
|
|
27
|
-
|
|
28
|
-
|
|
25
|
+
The implementer wrote and committed those tests in the Implement phase, before
|
|
26
|
+
the gate. Each test names the id of its criterion. `outerlayer work proofs
|
|
27
|
+
--record` finds those tests at HEAD, runs them through
|
|
28
|
+
`.outerlayer-proofs.yaml`, and emits each proof. The evidence agent runs them,
|
|
29
|
+
looks at what they record, and fixes what fails. It does not write a missing
|
|
30
|
+
demo test from the start. When its report names a criterion with no test,
|
|
31
|
+
spawn the implementer again with that list, to write those tests and nothing
|
|
32
|
+
else. Then spawn the evidence agent again. A capture script outside the tests
|
|
33
|
+
is not allowed, because no later session can run it again.
|
|
29
34
|
|
|
30
35
|
After the evidence agent returns, run `outerlayer sync`, then
|
|
31
36
|
`outerlayer work proofs --item "$OUTERLAYER_WORK"`. It lists each declared proof
|
|
@@ -45,10 +50,11 @@ In a runner build (`OUTERLAYER_JOB_DIR` is set), do not record a proof. Run
|
|
|
45
50
|
setup, tests and teardown as `--record`. It reports each proof as passed or
|
|
46
51
|
failed, and emits nothing. After the run ends, the host records each proof
|
|
47
52
|
once, at the pushed head. A proof that fails the check fails there too. Fix
|
|
48
|
-
its test, commit, and check again. The run ends when the check exits 0,
|
|
49
|
-
|
|
50
|
-
A
|
|
51
|
-
|
|
53
|
+
its test, commit, and check again. The run ends when the check exits 0,
|
|
54
|
+
apart from proofs this host cannot produce, as "Ending the run" in SKILL.md
|
|
55
|
+
says. A written reason excuses no other proof. A screenshot or video
|
|
56
|
+
criterion with no committed demo test goes back to the implementer, even
|
|
57
|
+
when the app does not start here.
|
|
52
58
|
|
|
53
59
|
In a local session, push the last commit, then run
|
|
54
60
|
`outerlayer work proofs --record` once. It records each proof that is not
|
|
@@ -73,12 +79,13 @@ ends. In a local session, the final report names each test proof with its
|
|
|
73
79
|
artifact. In a runner build, it names each test proof that passed the check.
|
|
74
80
|
|
|
75
81
|
In a local session, run the list command once more before the run ends. A
|
|
76
|
-
criterion still listed as out of date or missing
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
+
criterion still listed as out of date or missing needs a fix, unless this
|
|
83
|
+
host cannot produce its proof. In a runner build, the list shows each proof
|
|
84
|
+
as out of date or missing until the host records it. There, a proof that
|
|
85
|
+
fails `--check` needs a fix in the same way. `build-reports/evidence.md`
|
|
86
|
+
names each proof that still fails with its error, so the final report names
|
|
87
|
+
it as failed. A written reason never excuses a `failed` row. Never drive the
|
|
88
|
+
browser yourself.
|
|
82
89
|
|
|
83
90
|
Re-read the pull request's evidence comment. Resolve or escalate every row that
|
|
84
91
|
needs attention. A row is resolved when a re-read shows it, not when the fixing
|