@outerlayer/cli 0.22.0 → 0.22.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +4 -1
  3. package/dist/{agent-setup-XAJH6MPW.js → agent-setup-KXPDPTAJ.js} +6 -7
  4. package/dist/bridge-QFN3KJP6.js +8 -0
  5. package/dist/{build-GTMEADQD.js → build-6WRNZPVR.js} +4 -4
  6. package/dist/build-info.json +1 -1
  7. package/dist/{builder-OAUSTZHL.js → builder-G3MLDMTI.js} +4 -4
  8. package/dist/{check-3YHMJQ3P.js → check-N6WLZCER.js} +34 -34
  9. package/dist/{chunk-4NM3I3VV.js → chunk-276D7BJ7.js} +1 -1
  10. package/dist/{chunk-22DYXLU7.js → chunk-2CPOAPU4.js} +17 -17
  11. package/dist/{chunk-BLW6GPBZ.js → chunk-2Q3PZ42G.js} +1 -1
  12. package/dist/{chunk-IRBNIRQJ.js → chunk-3AZYLAJC.js} +4 -4
  13. package/dist/{chunk-ATRIVTRE.js → chunk-4542B3RR.js} +2 -2
  14. package/dist/{chunk-7V7KG3YM.js → chunk-4AVDD7VX.js} +2 -2
  15. package/dist/{chunk-JVB63NIB.js → chunk-4OYKJJ2V.js} +1 -1
  16. package/dist/{chunk-QOALB6ZD.js → chunk-B42BIYC6.js} +2 -2
  17. package/dist/{chunk-G6DZCKA6.js → chunk-BVR6MQLS.js} +2 -3
  18. package/dist/{chunk-KPBQYEND.js → chunk-CQAEV3Z5.js} +1 -1
  19. package/dist/{chunk-IZSVXRDR.js → chunk-DXDF43YG.js} +1 -1
  20. package/dist/{chunk-F7CU5ABH.js → chunk-DYEFPYME.js} +1 -1
  21. package/dist/{chunk-LOB2SUM3.js → chunk-EFB3FGLC.js} +1 -1
  22. package/dist/{chunk-JRCSET55.js → chunk-EMUNEAQK.js} +3 -3
  23. package/dist/{chunk-2HT2XGJX.js → chunk-FQE5RDHI.js} +5 -6
  24. package/dist/{chunk-EXV37PKS.js → chunk-FVDVC2GF.js} +1 -1
  25. package/dist/{chunk-5QRP3MVS.js → chunk-GNPTU4BM.js} +9 -4
  26. package/dist/{chunk-6IO62VJS.js → chunk-HWZCE745.js} +2 -2
  27. package/dist/{chunk-KIGSGZBB.js → chunk-IHNQWF6F.js} +1 -1
  28. package/dist/{chunk-C3OVGKVJ.js → chunk-IMCVQF5F.js} +5 -5
  29. package/dist/{chunk-WMHYIBJW.js → chunk-IPS2JCHK.js} +6 -6
  30. package/dist/{chunk-G2WME4RG.js → chunk-JD6GWYY7.js} +2 -3
  31. package/dist/{chunk-C3HKR67W.js → chunk-JV4YGAAW.js} +3 -3
  32. package/dist/{chunk-FGW2774C.js → chunk-KOIMUHIS.js} +16 -15
  33. package/dist/{chunk-PHHBYAL6.js → chunk-NYTZ7HVN.js} +1 -1
  34. package/dist/{chunk-I66MQDXH.js → chunk-OBCFK4QD.js} +2 -2
  35. package/dist/{chunk-KDHYLBRR.js → chunk-OW52QLK3.js} +1 -1
  36. package/dist/chunk-QS43O4DR.js +113 -0
  37. package/dist/{chunk-4JHVPFH6.js → chunk-QZX6DAAW.js} +9 -10
  38. package/dist/{chunk-UD3EXMKB.js → chunk-SFHR45FA.js} +21 -4
  39. package/dist/{chunk-KOQELWQ6.js → chunk-SNVXHNU7.js} +2 -3
  40. package/dist/{chunk-34XORKFD.js → chunk-U6RKHNC7.js} +6 -7
  41. package/dist/{chunk-2J5JGLW5.js → chunk-UF5L4BAI.js} +1 -1
  42. package/dist/{chunk-V7MQKOZY.js → chunk-URWYRAIC.js} +1 -1
  43. package/dist/{chunk-2CMJLYV6.js → chunk-V5CG75NX.js} +1 -1
  44. package/dist/{chunk-VX74ND77.js → chunk-WKSBSEWT.js} +8 -8
  45. package/dist/chunk-WXJXHZVB.js +73 -0
  46. package/dist/{chunk-ZFLOGMUC.js → chunk-XACXXKQ5.js} +1 -1
  47. package/dist/{chunk-WERZMIKA.js → chunk-XR56WEA5.js} +3 -3
  48. package/dist/{chunk-4QKLMNI3.js → chunk-ZCXP35T3.js} +5 -5
  49. package/dist/{claude-launcher-4BQNXYAF.js → claude-launcher-QD3C427Y.js} +1 -1
  50. package/dist/{cli-NMGVZQPB.js → cli-A2Y67WAB.js} +98 -91
  51. package/dist/{command-GE62AJZY.js → command-Q5Q2EIO4.js} +21 -22
  52. package/dist/{config-7Q52COZ3.js → config-H4QS332G.js} +2 -2
  53. package/dist/{connect-cmd-ZFOK6HEL.js → connect-cmd-TNGEIWCA.js} +7 -2
  54. package/dist/{control-plane-launch-SZTE4TUS.js → control-plane-launch-HE6OSWKO.js} +5 -6
  55. package/dist/{docker-2OVBKVRK.js → docker-JU422JL7.js} +4 -4
  56. package/dist/{doctor-3SQGZVYP.js → doctor-BRN4BGMA.js} +23 -24
  57. package/dist/{emit-artifact-cmd-R42BE6ID.js → emit-artifact-cmd-GPAJCCUC.js} +12 -12
  58. package/dist/{emit-criteria-cmd-MQZE7W4Y.js → emit-criteria-cmd-R3FKHSQG.js} +7 -7
  59. package/dist/{emit-finding-cmd-ZS5JEGGM.js → emit-finding-cmd-IK7RAVP5.js} +7 -7
  60. package/dist/{emit-result-cmd-FUE3DXBW.js → emit-result-cmd-5FJTF7YD.js} +12 -12
  61. package/dist/{emit-step-cmd-T7PRA44X.js → emit-step-cmd-VRTD5YPP.js} +8 -8
  62. package/dist/{exec-client-YIDTWXMZ.js → exec-client-ATPF2DDB.js} +3 -3
  63. package/dist/{governing-source-TORXL4I4.js → governing-source-WM736XR4.js} +9 -10
  64. package/dist/{guest-init-TO6HAWIT.js → guest-init-2OZ4YC7R.js} +4 -3
  65. package/dist/{hook-fast-WFB2ZMRB.js → hook-fast-QUGEI2IT.js} +1 -1
  66. package/dist/{hook-wrap-fast-NPLHJXFK.js → hook-wrap-fast-NOOGDNSW.js} +2 -2
  67. package/dist/{host-key-2LXQDSBO.js → host-key-ATB23GI3.js} +3 -3
  68. package/dist/index.js +6 -6
  69. package/dist/{init-2CRAVIUU.js → init-U3I43XCP.js} +20 -21
  70. package/dist/{init-AHDZCMDC.js → init-X7FCQDFX.js} +20 -21
  71. package/dist/{init-cmd-IXDL2ZSL.js → init-cmd-VCKH2DUQ.js} +13 -14
  72. package/dist/{init-update-YB3PODDH.js → init-update-TCMH7M3Q.js} +7 -8
  73. package/dist/{install-CZUIW2AF.js → install-SFACZU7E.js} +4 -4
  74. package/dist/{install-cmd-Q7RJGFUO.js → install-cmd-6HTP7I43.js} +5 -5
  75. package/dist/{logs-RJPYTVQE.js → logs-N3ZX7HFV.js} +2 -2
  76. package/dist/{loop-ZDW6TRAA.js → loop-P3QDQOE5.js} +34 -34
  77. package/dist/{machine-JCOHLASP.js → machine-EEFOW32K.js} +16 -17
  78. package/dist/{mcp-serve-cmd-IULQPVHL.js → mcp-serve-cmd-TQSPFRC7.js} +5 -5
  79. package/dist/{paths-N3LU4O2Z.js → paths-AKX2OOLF.js} +2 -2
  80. package/dist/{pending-GRCV3ZR4.js → pending-7SGWZCEH.js} +3 -3
  81. package/dist/{pidfile-IF3TCL5A.js → pidfile-G2J5WBQS.js} +3 -3
  82. package/dist/{record-73PQE77B.js → record-Q4IEYIVV.js} +3 -3
  83. package/dist/{runner-env-LDOBJESN.js → runner-env-GZHXM27A.js} +5 -5
  84. package/dist/{runner-identity-RWCBTY2A.js → runner-identity-FTHZFMGY.js} +4 -4
  85. package/dist/{runner-key-HMYLP6WN.js → runner-key-O42EUXQU.js} +20 -21
  86. package/dist/{session-sender-2G25JYHI.js → session-sender-HF6DXFA2.js} +13 -13
  87. package/dist/{settings-J2652U5N.js → settings-AKYEOCC2.js} +1 -1
  88. package/dist/{spec-cmd-LBVXM6XS.js → spec-cmd-ADPH236D.js} +8 -8
  89. package/dist/{status-QZB2GWXJ.js → status-LXFIVGP3.js} +25 -25
  90. package/dist/{statusline-fast-2OK3DVAA.js → statusline-fast-GVRSBHAF.js} +2 -2
  91. package/dist/{sync-cmd-TQQIR4PN.js → sync-cmd-5XS3CUV5.js} +12 -12
  92. package/dist/{watch-4JES4PCS.js → watch-FBZHZV56.js} +12 -12
  93. package/dist/{work-claim-cmd-XG6O7B63.js → work-claim-cmd-LIIINECF.js} +11 -11
  94. package/dist/{work-cmd-L6WMPAA2.js → work-cmd-SM6DY2WK.js} +8 -8
  95. package/dist/{work-comment-cmd-SNTDCPGH.js → work-comment-cmd-VYVXGT4W.js} +8 -8
  96. package/dist/{work-logs-cmd-3S7IAVII.js → work-logs-cmd-XZSCWWMW.js} +8 -8
  97. package/dist/{work-open-pr-cmd-E3WMO5XT.js → work-open-pr-cmd-YZNC3P3R.js} +9 -9
  98. package/dist/{work-pr-cmd-22T6FG4T.js → work-pr-cmd-AMN23KFJ.js} +8 -8
  99. package/dist/{work-stop-cmd-WR7ESS4Z.js → work-stop-cmd-HSR2GOJJ.js} +8 -8
  100. package/package.json +1 -1
  101. package/skill-pack/maintained/outerlayer-amend/SKILL.md +90 -78
  102. package/skill-pack/maintained/outerlayer-build/SKILL.md +4 -2
  103. package/skill-pack/maintained/outerlayer-build/references/agent-briefs.md +10 -3
  104. package/skill-pack/maintained/outerlayer-build/references/release.md +7 -4
  105. package/skill-pack/maintained/outerlayer-build/references/review-briefs.md +6 -3
  106. package/skill-pack/maintained/outerlayer-cli/SKILL.md +8 -1
  107. package/skill-pack/maintained/outerlayer-cli/references/merge-base-branch.md +54 -0
  108. package/dist/chunk-NTRCK4NH.js +0 -38
  109. package/dist/chunk-VWLOQ6FI.js +0 -56
@@ -3,9 +3,10 @@ name: outerlayer-amend
3
3
  description: >
4
4
  Answer the review threads waiting on an agent on an open pull request: read each
5
5
  thread a person handed to an agent, fix what it says on the pull request's branch,
6
- reply on the thread with a replacement artifact or a sentence, and push. Use when a
7
- work item has threads waiting on an agent, or when asked to "answer the review" or
8
- "fix what the reviewer failed". Invoke with /outerlayer-amend.
6
+ reply on the thread with a replacement artifact or a sentence, and push. Also resolve a
7
+ merge conflict with the base branch. Use when a work item has threads waiting on an
8
+ agent or a conflicting pull request, or when asked to "answer the review" or "fix what
9
+ the reviewer failed". Invoke with /outerlayer-amend.
9
10
  ---
10
11
 
11
12
  Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule.
@@ -13,11 +14,10 @@ Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerl
13
14
  Answer every thread waiting on an agent on one work item's pull request, then
14
15
  stop. A work item has one general thread and one thread per acceptance
15
16
  criterion. A person's fail on the general thread leaves it waiting on an agent.
16
- A note a reviewer sent with Request changes (a sent note) leaves its criterion
17
- thread waiting on an agent. A plain comment from a person does not hand a
18
- thread to an agent. The person's newest comment says what they want. This
19
- skill never records a verdict. Only a person passes or fails a thread. A
20
- session can only reply.
17
+ A note a reviewer sent with Request changes (a sent note) does the same to its
18
+ criterion thread. A plain comment from a person does not hand a thread to an
19
+ agent. The person's newest comment says what they want. Only a person passes
20
+ or fails a thread. A session can only reply.
21
21
 
22
22
  A session never records a pass or fail on an artifact.
23
23
 
@@ -26,118 +26,130 @@ request's branch first if the working tree is not already on it.
26
26
 
27
27
  ## Arguments
28
28
 
29
- - `--unattended`: no person is watching. Never ask a question. Anything that
30
- needs a person becomes a hand-off (step 5), never a stop that leaves a thread
31
- silently waiting on an agent.
29
+ - `--unattended`: no person is watching. Never ask a question. A need for a
30
+ person becomes a hand-off (step 7), never a silent stop.
32
31
 
33
32
  ## Builds and local sessions
34
33
 
35
34
  A session a runner started for the item is a build. `OUTERLAYER_JOB_DIR` is
36
- set in a build and nowhere else. The GitHub token a runner gives a build can
37
- read the issue and the pull request but cannot comment on either. In the
38
- runner's own build environments, git pushes go through the runner, not
39
- straight to the git host. A local session uses the person's own git remote and
40
- `gh` login.
35
+ set in a build and nowhere else. A build's GitHub token cannot comment on the
36
+ issue or the pull request, and its git pushes go through the runner. A local
37
+ session uses the person's own git remote and `gh` login.
41
38
 
42
39
  ## Several repositories
43
40
 
44
- A build can hold several repositories. `OUTERLAYER_REPOSITORIES` lists them,
45
- each with its `path`, `branch` and whether it is `primary`. The item can have a
46
- pull request in more than one of them. Make each fix in the checkout of the
47
- repository whose pull request the thread is about, and commit and push in each
48
- checkout you change. A push goes only to that checkout's own branch.
41
+ `OUTERLAYER_REPOSITORIES` lists the repositories of a build, each with its
42
+ `path`, `branch` and whether it is `primary`. The item can have a pull request
43
+ in more than one. Make each fix in the checkout of the repository whose pull
44
+ request the thread is about. Commit and push in each checkout you change, to
45
+ its own branch only.
49
46
 
50
47
  ## Steps
51
48
 
52
- 1. **Read the threads.**
49
+ 1. **Resolve a merge conflict.** Run
50
+ `outerlayer work status --item "$OUTERLAYER_WORK" --json`. For each
51
+ `pullRequests` entry, compare `conflict.headSha` with `git rev-parse HEAD`
52
+ in that repository's checkout. Skip an entry whose `conflict` is `null` or
53
+ differs: a push has moved the head. Do this before any thread, and go on
54
+ even when none waits.
55
+ For a matching entry, merge the base branch into the pull request's branch.
56
+ Never rebase and never force-push. Follow
57
+ `.outerlayer/skills/outerlayer-cli/references/merge-base-branch.md`. Run the
58
+ pre-push gate in the foreground. Name the base sha in the merge commit.
59
+ Push, then answer the threads.
60
+ **Hand off a conflict you cannot resolve.** If the resolution needs a
61
+ product decision, or the gate stays red after one fix, abort the merge.
62
+ Push nothing. Post on the general thread with `--ready`. Name the
63
+ conflicting files, the base commits behind them and the decision needed.
64
+ Tell the person to fail the general thread with their answer.
65
+ 2. **Read the threads.**
53
66
  `outerlayer work threads --item "$OUTERLAYER_WORK" --json` prints
54
67
  `{ "general": <thread>, "criteria": [<thread>, ...] }`. Each thread carries
55
68
  `criterion` (null for the general thread), `waitingOn` (`agent`, `person` or
56
69
  null), `verdict`, `proof` and `comments`. Each comment carries `author`
57
70
  (`kind` is `person` or `agent`), `body`, `action` and `artifact`. Keep the
58
- threads whose `waitingOn` is `agent`. One send of notes starts one run, so
59
- expect several criterion threads and the general thread together. If none is
60
- waiting, say so and stop: there is nothing to answer. Then read
61
- `outerlayer work status --item "$OUTERLAYER_WORK" --json` for the pull
62
- request in `pullRequests` (`repository`, `prNumber`).
63
- 2. **Re-orient.** Read the issue the item names from the status JSON's
64
- `issue`, OuterLayer's copy of it, which needs no tracker credential:
65
- `issue.body` is its description in Markdown. Read the pull request,
66
- including its evidence comment, through the git host. The
67
- issue body is the spec. Find each thread's criterion there. Read every
68
- person's comment since the last agent comment on the thread. Read them
69
- literally: they are the reviewer's instruction.
70
- 3. **Decide each thread.** Reply on every criterion thread waiting on an
71
+ threads whose `waitingOn` is `agent`: one send of notes can leave several.
72
+ If none is waiting and step 1 resolved no conflict, say so and stop: there
73
+ is nothing to answer. Take the pull request (`repository`, `prNumber`) from
74
+ the `pullRequests` of the status JSON you read in step 1.
75
+ 3. **Re-orient.** The status JSON's `issue.body` is OuterLayer's copy of the
76
+ issue. It is the spec: find each thread's criterion there. Read the pull
77
+ request, with its evidence comment, through the git host. Read every person's comment since the last agent
78
+ comment on the thread. Read them literally.
79
+ 4. **Decide each thread.** Reply on every criterion thread waiting on an
71
80
  agent, with `--criterion`, so each note gets its answer under it. Read each
72
81
  note and pick one:
73
82
  - **Answer it.** A question gets an answer. Reply with the answer and
74
83
  change nothing. Say which file or test you looked at.
75
- - **Fix it.** A requested change gets a fix. The comment names something the
76
- change got wrong or did not show. Change the code, tests, docs or evidence
77
- so the criterion is met as written, and attach new proof when the
84
+ - **Fix it.** A requested change gets a fix. Change the code, tests, docs or
85
+ evidence so the criterion is met as written, and attach new proof when the
78
86
  criterion declares one.
79
- - **The spec is wrong.** The comment shows the criterion cannot be met as
80
- written, for example because it names a path a repository rule forbids. A
81
- session never rewrites a criterion on its own. Hand it off (step 5), naming
82
- the exact wording change the owner should make.
87
+ - **The spec is wrong.** The criterion cannot be met as written, for
88
+ example because it names a path a repository rule forbids. A session never
89
+ rewrites a criterion. Hand it off (step 7), naming the wording change the
90
+ owner should make.
83
91
  - **Cannot tell.** The comment is ambiguous. Hand it off with `--ready`:
84
- quote it and ask one question back.
85
- 4. **Fix, prove, reply.** An answer needs no commit: reply on its criterion
92
+ quote it and ask one question.
93
+ 5. **Fix, prove, reply.** An answer needs no commit: reply on its criterion
86
94
  thread with the answer and `--ready`. For each thread you fix:
87
- - Make the change on the pull request's branch. Keep it to what the comment
88
- asks. Do not refactor around it.
89
- - Run the tests that cover the criterion, then the repository's full
90
- pre-push checks through a normal `git push`. Never bypass a hook.
91
- - A runner accepts a build's push only to the pull request's branch. If it
92
- refuses one, read the reason git prints, fix it and push again.
93
- - In a local session over SSH, the git host can drop the connection during
94
- a long gate. Push again with
95
+ - Change only what the comment asks, on the pull request's branch.
96
+ - Run the tests that cover the criterion, then the repository's pre-push
97
+ checks through a normal `git push`. Never bypass a hook.
98
+ - If the runner refuses a push, read the reason git prints, fix it and push
99
+ again.
100
+ - Over SSH, a long gate can drop the connection. Push again with
95
101
  `GIT_SSH_COMMAND="ssh -o ServerAliveInterval=20 -o ServerAliveCountMax=60"`.
96
- - **When the thread asks for new proof** (a criterion thread whose proof the
97
- person failed), capture it after the fixed state exists, in the form the
98
- criterion declares (`proof: screenshot` and so on) or the form of the
99
- current proof. Emit it bound to that criterion, without `--replaces`.
100
- Attaching it on the thread supersedes the old proof.
102
+ - **When the thread asks for new proof** (a person failed its proof),
103
+ capture it after the fixed state exists, in the form the criterion
104
+ declares or the form of the current proof. Emit it bound to that
105
+ criterion, without `--replaces`:
101
106
  `outerlayer emit artifact <file> --caption "<what it shows>" --for <criterion>`.
102
- Note the id it prints. Run `outerlayer sync` so the artifact reaches the
103
- server. The attach looks it up there and refuses an artifact it cannot
104
- find. Then reply:
107
+ Note the id it prints. Run `outerlayer sync`, so the attach can find the
108
+ artifact. Then reply, which supersedes the old proof:
105
109
  `outerlayer work comment --item "$OUTERLAYER_WORK" --criterion <criterion> --body "<what changed>" --artifact <uuid> --attach`.
106
- A replacement whose bytes match the current proof is flagged `unchanged`
107
- and keeps the turn where the person's comment left it, so the thread
108
- still waits on you.
110
+ A replacement whose bytes match the current proof is flagged `unchanged`,
111
+ so the thread still waits on you.
109
112
  - **Otherwise** (the general thread, or a fix that needs no new proof),
110
113
  reply with a sentence naming what changed and the commit:
111
114
  `outerlayer work comment --item "$OUTERLAYER_WORK" [--criterion <criterion>] --body "<what changed>" --ready`.
112
115
  Omit `--criterion` on the general thread.
113
- 5. **Hand off what you cannot fix.** Reply on the thread with `--ready` and a
114
- body of one sentence of fact, then the decision a person must make. For a
115
- spec problem, quote the criterion and give the replacement wording.
116
- `--ready` hands the thread back to a person.
117
- 6. **Check nothing is left waiting.** Read the threads again. No thread you
118
- started with may still be waiting on an agent. If one is, the reply did not
119
- land or was flagged `unchanged`. Find out why and fix it, or report it.
120
- 7. **Report.** Write one line per thread, naming the criterion (or the general
116
+ 6. **Watch CI.** Skip this step when you pushed nothing. Run
117
+ `gh pr checks <prNumber> --repo <repository> --watch` on each pull request
118
+ you pushed. Leave out any check that waits on results recorded after the
119
+ session ends. "No checks reported" is not green: query again.
120
+ - For a failed check, read `gh run view <run-id> --log-failed`, fix it, push
121
+ again.
122
+ - If it also fails on the base branch, or failed outside the code,
123
+ change nothing.
124
+ - Stop after two fixes for one check.
125
+ 7. **Hand off what you cannot fix.** Reply on the thread with `--ready`: one
126
+ sentence of fact, then the decision a person must make. For a spec problem,
127
+ quote the criterion and give the replacement wording. `--ready` hands the
128
+ thread back to a person.
129
+ 8. **Check nothing is left waiting.** Read the threads again. None you started
130
+ with may still wait on an agent. If one does, the reply did not land or was
131
+ flagged `unchanged`. Fix that, or report it.
132
+ 9. **Report.** Write one line per thread, naming the criterion (or the general
121
133
  thread) and saying fixed (with the replacement) or handed off (with the
122
- reason). Plain language. No session labels, no raw command output. Post the
134
+ reason). Add one line for a merge conflict: merged, with the base sha, or
135
+ handed off, with the reason. Add a CI line when you pushed: green, or each
136
+ red check and why. Use plain language. Post the
123
137
  lines once on the general thread, in a build and in a local session alike:
124
138
  `outerlayer work comment --item "$OUTERLAYER_WORK" --body "<the lines>"`.
125
139
  A plain comment from an agent leaves the general thread waiting on a person.
126
- A local session also posts the lines once as a pull request comment. A build
127
- does not try: its token cannot comment. End the session with the same lines.
140
+ A local session also posts them on the pull request. A build does not:
141
+ its token cannot comment. End with the same lines.
128
142
 
129
143
  ## Rules
130
144
 
131
145
  - **Answer only threads waiting on an agent.** A thread waiting on a person, or
132
146
  on no one, is not yours to reply on.
133
147
  - **One thread, one proof.** Never attach an artifact that does not prove that
134
- thread's criterion. The attach refuses an artifact bound to a different
135
- criterion.
148
+ thread's criterion.
136
149
  - **A person decides.** Never pass `--pass` or `--fail`, never mark a check as
137
150
  a person, and never edit the issue's criteria.
138
151
  - **Stay on the branch.** Push to the pull request's own branch. Never open a
139
152
  second pull request in a repository that has one, and never force-push over
140
153
  someone else's commits.
141
154
  - **Write for a reader who was not here.** Every comment, commit and reply
142
- follows the repository's writing rule: outcome first, short sentences, plain
143
- words.
155
+ follows the repository's writing rule: outcome first, short plain sentences.
@@ -89,7 +89,9 @@ Given a request instead of a work item, stop and say:
89
89
  Optional flag: `--unattended` means no person is present and nothing wakes
90
90
  the session after a turn ends. Spawn every agent in the foreground and wait
91
91
  for it in the same turn. Run the gate in the foreground with the maximum
92
- timeout. End the turn only at the final report.
92
+ timeout. A command that outlives that timeout continues in the background:
93
+ wait for it in the foreground before you use its result. End the turn only at
94
+ the final report.
93
95
 
94
96
  ## State rules
95
97
 
@@ -305,7 +307,7 @@ Run them in order.
305
307
 
306
308
  5. **Pull request.** Run `outerlayer emit step "Pull request" --item "$OUTERLAYER_WORK"`,
307
309
  then apply the team's changes for this phase. Read [references/release.md](references/release.md)
308
- on entry and run it. A release agent rebases, gates and pushes. Open the
310
+ on entry and run it. A release agent merges the base branch in, gates and pushes. Open the
309
311
  pull request as release.md says: a runner build with `outerlayer work open-pr`,
310
312
  which links it, and a local session with `gh pr create` and then
311
313
  `outerlayer work pr <number>`. When the build recorded criteria, from the issue or drafted, a fresh agent judges them with
@@ -45,6 +45,13 @@ Run every long command, such as the full gate, the mutation tool or the
45
45
  integration suite, in the foreground with the maximum timeout. Never
46
46
  background one, and never end a turn waiting on a notification.
47
47
 
48
+ A command that runs past the maximum timeout moves to the background and
49
+ continues. It has not finished. Wait for it in the foreground before you use
50
+ or report its result. For a command named `run-checks`, wait with
51
+ `while pgrep -f '[r]un-checks' >/dev/null; do sleep 15; done`. Keep the
52
+ brackets around the first letter of the name. Without them, `pgrep` on Linux
53
+ finds the waiting shell, and the loop does not stop.
54
+
48
55
  Every agent in a run shares one memory cap. Run only the test files for the
49
56
  code you change or check, one at a time. Run a whole package's suite, a
50
57
  coverage run, a repository-wide typecheck or the full gate only where this
@@ -181,9 +188,9 @@ The shared rules apply. Your inputs are the state file path, the branch and
181
188
  the instructions-file pointer. You run no write command against the tracker
182
189
  or the git host beyond the push.
183
190
 
184
- Fetch the base branch, then rebase the branch onto it. Merge instead once the
185
- branch is pushed and someone else may hold it. Resolve every conflict on the
186
- branch, never in a web editor.
191
+ Bring the base branch into the branch as
192
+ `.outerlayer/skills/outerlayer-cli/references/merge-base-branch.md` says.
193
+ Resolve every conflict on the branch, never in a web editor.
187
194
 
188
195
  A migration this branch adds whose version is at or below the newest one on
189
196
  the base branch is renamed to the current UTC time, with every reference to
@@ -9,10 +9,13 @@ file, not from the transcript.
9
9
 
10
10
  The orchestrator does not sync, run the gate, push or watch CI itself. Spawn
11
11
  one release agent in a fresh context on the "sync and push" brief, with the
12
- state file path, the branch and the instructions-file pointer. A check that
13
- fails there has the standing of a red gate and returns to the review phase's
14
- remaining budget. If its report names files the sync moved that the review had
15
- already cleared, run one check round on the rebased diff before going on.
12
+ state file path, the branch and the instructions-file pointer. The agent
13
+ brings the base branch in as
14
+ `.outerlayer/skills/outerlayer-cli/references/merge-base-branch.md` says. A
15
+ check that fails there has the standing of a red gate and returns to the
16
+ review phase's remaining budget. If its report names files the sync moved that
17
+ the review had already cleared, run one check round on the merged diff before
18
+ going on.
16
19
 
17
20
  ## Open the pull request
18
21
 
@@ -259,9 +259,12 @@ shared tree while you run, so no mutation may touch it.
259
259
 
260
260
  1. Run the repository's changed-lines mutation tool once over the whole diff.
261
261
  Every survivor it reports is a finding. Never rerun it per file, never
262
- lower its budget, and never run a whole suite or a coverage run. A run
263
- that ends over budget is reported as over budget with the mutants it
264
- scored. One rerun is allowed, and only when the tool reports no result
262
+ lower its budget, and never run a whole suite or a coverage run. The
263
+ tool can run longer than your shell's maximum timeout. Then your shell
264
+ moves it to the background. Wait for it to exit before you write your
265
+ report. Only the tool's own output can say that a run went over budget.
266
+ A run that ends over budget is reported as over budget with the mutants
267
+ it scored. One rerun is allowed, and only when the tool reports no result
265
268
  because a workspace dependency could not be resolved: build the
266
269
  dependencies, then run once more.
267
270
  2. Read the tool's report. For each criterion whose production lines were
@@ -38,7 +38,7 @@ from the output of `outerlayer work build`.
38
38
  4. `outerlayer emit artifact <file> --caption "<what it shows>"` attaches a
39
39
  screenshot, recording, report or log as evidence. The `outerlayer-evidence`
40
40
  skill says what to capture.
41
- 5. `/outerlayer-amend` answers the review threads a person handed to an agent.
41
+ 5. `/outerlayer-amend` answers the review threads a person handed to an agent. It also resolves a merge conflict on a pull request a host built.
42
42
 
43
43
  ## Several repositories
44
44
 
@@ -76,6 +76,13 @@ ended, which session ran in it, and what the runner did around the agent. The
76
76
  steps, and what each outcome and reason means, are in
77
77
  [references/find-out-why-a-build-ended.md](references/find-out-why-a-build-ended.md).
78
78
 
79
+ ## Merging the base branch
80
+
81
+ A build merges the base branch into its branch before the pull request opens.
82
+ A run that resolves a merge conflict does the same on an open pull request.
83
+ Both follow one procedure in
84
+ [references/merge-base-branch.md](references/merge-base-branch.md).
85
+
79
86
  ## Reading work items
80
87
 
81
88
  When the OuterLayer MCP server is configured in this repository, its
@@ -0,0 +1,54 @@
1
+ # Merge the base branch into a branch
2
+
3
+ Use this procedure when a branch must take in its base branch: a build's
4
+ last sync before the pull request opens, and a run that resolves a merge
5
+ conflict on a pull request already open. It is the one written procedure
6
+ for both.
7
+
8
+ Merge the base branch. Never rebase, and never force-push. A merge keeps the
9
+ commits a reviewer already read and keeps review comments on their lines.
10
+
11
+ 1. Fetch the base branch. Use the pull request's base, which the item's
12
+ `outerlayer work status --item "$OUTERLAYER_WORK" --json` names in
13
+ `pullRequests[].conflict.baseBranch`, or the repository's default branch
14
+ when the pull request has no conflict record.
15
+
16
+ git fetch origin <base>
17
+
18
+ 2. Record the base commit you merge. Read it after the fetch.
19
+
20
+ git rev-parse origin/<base>
21
+
22
+ 3. Merge it into the checked-out branch, and stop before git commits.
23
+
24
+ git merge origin/<base> --no-commit --no-ff
25
+
26
+ If git reports `Already up to date`, the branch holds the base already.
27
+ Stop: there is nothing to push. If the merge has no conflict, go to step 5.
28
+
29
+ 4. Resolve each conflict so that the result keeps the intent of both sides.
30
+ List the conflicting files with `git diff --name-only --diff-filter=U`.
31
+ For each file, read the base commits that changed it
32
+ (`git log --oneline HEAD..origin/<base> -- <file>`) and the work item's
33
+ spec. Do not pick one side to make the conflict go away. Mark a file
34
+ resolved with `git add <file>` only when its code and its tests agree
35
+ with both sides.
36
+
37
+ 5. Run the repository's pre-push gate in the foreground, with the maximum
38
+ timeout. It names its own command in the repository's instructions file.
39
+ Wait for it to end. If the gate fails, fix the cause and run it again once.
40
+ A second failure is a hand-off, not a third try.
41
+
42
+ 6. Commit the merge. Name the base sha from step 2 in the message, so a reader
43
+ can find the exact base commit.
44
+
45
+ git commit -m "Merge <base> at <base sha> into <branch>"
46
+
47
+ 7. Push the branch. The hooks run, and you never bypass them. A push goes to
48
+ the pull request's own branch only.
49
+
50
+ ## When you cannot resolve it
51
+
52
+ Abort the merge with `git merge --abort`. The branch returns to the state it
53
+ had before step 3. Push nothing. Hand the item to a person in the way the
54
+ calling skill says.
@@ -1,38 +0,0 @@
1
- #!/usr/bin/env node
2
- import { createRequire } from 'node:module';
3
- import { readRepoConnection, findGitDirs } from './chunk-BJ3KTMDH.js';
4
- import { readCloudConfig } from './chunk-EABW6AJQ.js';
5
- import { cliInvocation } from './chunk-CRB3POP4.js';
6
- import { homeFromEnv } from './chunk-VNVZDWO3.js';
7
-
8
- createRequire(import.meta.url);
9
-
10
- // src/credentials.ts
11
- var MISSING_HELP = `Run \`${cliInvocation()} login\` to sign in, or set OUTERLAYER_URL / OUTERLAYER_API_KEY / OUTERLAYER_APP_ID. Mint a key in the dashboard: Settings \u2192 API keys.`;
12
- var NO_FACTORY_MESSAGE = `you are logged in, but no factory is chosen for this repository. Run \`${cliInvocation()} connect\` to choose one, or pass --app-id / set OUTERLAYER_APP_ID.`;
13
- var NO_FACTORY_OUTSIDE_REPOSITORY_MESSAGE = "you are logged in, but this directory is not in a git repository, so no factory is chosen. Pass --app-id / set OUTERLAYER_APP_ID, or run this from inside a connected repository.";
14
- var LOGIN_TOKEN_PREFIX = "olu_";
15
- function unauthorizedMessage(credential) {
16
- return credential.startsWith(LOGIN_TOKEN_PREFIX) ? `not authorized \u2014 the login is expired or was revoked. Run \`${cliInvocation()} login\` to sign in again.` : "not authorized \u2014 the API key is unknown, expired, or bound to a different factory. Mint a fresh key: dashboard \u2192 Settings \u2192 API keys.";
17
- }
18
- function resolveGatewayCredentials(sources = {}) {
19
- const env = sources.env ?? process.env;
20
- const config = readCloudConfig(sources.home ?? homeFromEnv(env));
21
- const url = sources.url ?? env.OUTERLAYER_URL ?? config.url;
22
- const key = sources.apiKey ?? (env.OUTERLAYER_API_KEY || void 0) ?? config.apiKey;
23
- const kind = key ? "key" : "login";
24
- const credential = key ?? config.accountToken;
25
- const cwd = sources.cwd ?? process.cwd();
26
- const appId = sources.appId ?? (env.OUTERLAYER_APP_ID || void 0) ?? (kind === "key" ? config.appId : readRepoConnection(cwd)?.appId);
27
- if (credential && url && !appId && kind === "login") {
28
- const message = findGitDirs(cwd) === void 0 ? NO_FACTORY_OUTSIDE_REPOSITORY_MESSAGE : NO_FACTORY_MESSAGE;
29
- return { ok: false, message, url, credential, appId, kind };
30
- }
31
- if (!url || !credential || !appId) {
32
- const missing = [!url && "--url", !credential && "a login or OUTERLAYER_API_KEY", !appId && "--app-id"].filter(Boolean).join(", ");
33
- return { ok: false, message: `missing ${missing}. ${MISSING_HELP}`, url, credential, appId, kind };
34
- }
35
- return { ok: true, url, credential, appId, kind };
36
- }
37
-
38
- export { resolveGatewayCredentials, unauthorizedMessage };
@@ -1,56 +0,0 @@
1
- #!/usr/bin/env node
2
- import { createRequire } from 'node:module';
3
- import { readCloudConfig, cloudConfigPath } from './chunk-EABW6AJQ.js';
4
- import { homeFromEnv } from './chunk-VNVZDWO3.js';
5
- import { signRunnerRequest, signerFor } from './chunk-KDHYLBRR.js';
6
-
7
- createRequire(import.meta.url);
8
-
9
- // src/signing-fetch.ts
10
- function bodyBytes(body) {
11
- if (body === void 0 || body === null) return new Uint8Array(0);
12
- if (typeof body === "string") return new TextEncoder().encode(body);
13
- if (body instanceof Uint8Array) return body;
14
- if (body instanceof ArrayBuffer) return new Uint8Array(body);
15
- return void 0;
16
- }
17
- async function savedKeySigner(headers, home) {
18
- const authorization = headers.get("authorization");
19
- if (authorization === null || !authorization.startsWith("Bearer ")) return void 0;
20
- if (headers.has("signature")) return void 0;
21
- if (readCloudConfig(home).apiKey !== authorization.slice("Bearer ".length)) return void 0;
22
- try {
23
- return await signerFor(cloudConfigPath(home));
24
- } catch {
25
- return void 0;
26
- }
27
- }
28
- function signedBy(base, signerOf) {
29
- return (async (input, init) => {
30
- if (input instanceof Request) return base(input, init);
31
- const headers = new Headers(init?.headers);
32
- const signer = await signerOf(headers);
33
- const body = bodyBytes(init?.body);
34
- if (signer === void 0 || body === void 0) return base(input, init);
35
- const signature = await signRunnerRequest({ method: init?.method ?? "GET", url: input.toString(), body, signer });
36
- for (const [name, value] of Object.entries(signature)) headers.set(name, value);
37
- return base(input, { ...init, headers });
38
- });
39
- }
40
- function signingFetch(base, home = () => homeFromEnv()) {
41
- return signedBy(base, (headers) => savedKeySigner(headers, home()));
42
- }
43
- function signingFetchFor(base, configPath, apiKey) {
44
- return signedBy(base, async (headers) => {
45
- const authorization = headers.get("authorization");
46
- if (authorization !== `Bearer ${apiKey}` || headers.has("signature")) return void 0;
47
- try {
48
- return await signerFor(configPath);
49
- } catch {
50
- return void 0;
51
- }
52
- });
53
- }
54
- var defaultFetch = signingFetch((input, init) => globalThis.fetch(input, init));
55
-
56
- export { defaultFetch, signingFetchFor };