@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.
@@ -1 +1 @@
1
- {"id":"2026-11-16T13:30:35.989Z","root":"/home/runner/work/outerlayer/outerlayer","pkg":"outerlayer"}
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.20261116130619",
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. Write and commit the demo test and the
376
- file-proof tests. Each test uses the id of the criterion it records a proof for. When the
377
- repository has no `.outerlayer-proofs.yaml`, write and commit one. In a
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, or when `build-reports/evidence.md` names each
404
- proof that failed and the reason. Do not run `--record`: the host records each
405
- proof at the pushed head. A row marked `failed` fails the check, and no reason
406
- excuses it: add or change a test that proves the criterion, commit, and check
407
- again.
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, or when `build-reports/evidence.md` names each proof it still lists
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 criterion
210
- is not evidenced, and `evidence.md` says why. Before emitting, look at each
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
- Write the demo, when a criterion needs a video or a screenshot, as a Playwright
214
- test that is part of the change. Put it where the repository keeps its Playwright tests, in the
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
- - The repository has one `.outerlayer-proofs.yaml` at its root. When it is
231
- missing, write it and commit it. `setup` lists the commands that seed and start
232
- the app. Each setup command must return once the app is ready. `teardown`
233
- lists the commands that stop it. Each entry in `runners` has a `files` glob of
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 that no test can make stays without a test. Give the reason in
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 that no test can
277
- make. Read the error and fix the cause. If you cannot, still write and
278
- commit the test for each criterion. Then quote the command and its error in
279
- `build-reports/evidence.md`. Without a committed test, no later job can
280
- record the proof.
281
-
282
- Commit the setup file and every test. In a runner build (`OUTERLAYER_JOB_DIR`
283
- is set), run `outerlayer work proofs --check` from the committed checkout. In a
284
- local session, run `outerlayer work proofs --record`. Each stops when a
285
- tracked file differs from HEAD, and runs only what is committed at HEAD. Each
286
- skips a proof that is current. `--record` emits each proof at HEAD. `--check`
287
- emits nothing, because the host records each proof at the pushed head. Never emit by hand
288
- a proof that a test can make, except a `test` proof the first time, as above. Always pass `--pr <number>` when the item links
289
- more than one pull request in the repository.
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, or
299
- with the reason none could be produced. A criterion you could not evidence is
300
- a result, not a gap to leave silent.
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. The evidence agent records it as a chapter of the item's demo, with a
19
- `demo.screenshot()` call. It emits a screenshot with `emit artifact` only for a
20
- state no demo test can reach. One that declares `proof: video` needs a video: its chapter of the
21
- item's one demo. A screenshot never satisfies `proof: video`. A criterion that declares `proof: test` needs
22
- passing test results at the head commit. A criterion with `proof: null` is one a person proves, and needs no artifact.
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 evidence agent captures every proof from tests it commits with the
25
- change. Each test names the id of its criterion. `outerlayer work proofs --record`
26
- finds those tests at HEAD, runs them through `.outerlayer-proofs.yaml`, and emits
27
- each proof. A capture script outside the tests is not allowed, because no later
28
- session can run it again.
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, or
49
- when `build-reports/evidence.md` names each proof that failed and the reason.
50
- A screenshot or video criterion with no committed demo test is not ready for
51
- that file. Write its test first, even when the app does not start here.
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 goes in
77
- `build-reports/evidence.md` with the reason. In a runner build, the list shows
78
- each proof as out of date or missing until the host records it. There, a
79
- proof that fails `--check` goes in `build-reports/evidence.md` with the
80
- reason. A written reason never excuses a `failed` row. Fix it first. Never
81
- drive the browser yourself.
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