@azure-id/orc 1.9.2 → 2.0.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 (172) hide show
  1. package/CHANGELOG.md +321 -0
  2. package/README-id.md +21 -36
  3. package/README.md +25 -36
  4. package/bin/build-agents.js +117 -20
  5. package/bin/cli.js +725 -29
  6. package/bin/gotcha-import.js +1081 -0
  7. package/bin/gotcha.js +1286 -0
  8. package/bin/graph-query.js +1 -1
  9. package/bin/graph.js +717 -717
  10. package/bin/habit.js +1453 -0
  11. package/bin/mockrun-catalog.js +281 -276
  12. package/bin/run-undo.js +398 -0
  13. package/bin/trace-write.js +657 -0
  14. package/bin/verify-contracts.js +525 -79
  15. package/bin/verify-package.js +51 -4
  16. package/bin/webui/api.js +26 -0
  17. package/bin/webui/app.html +239 -232
  18. package/bin/webui/css/00-tokens.css +110 -92
  19. package/bin/webui/css/04-motion.css +87 -0
  20. package/bin/webui/css/06-responsive.css +203 -178
  21. package/bin/webui/css/panels/behaviour.css +205 -0
  22. package/bin/webui/fixtures/behaviour.js +532 -0
  23. package/bin/webui/fixtures/index.js +34 -0
  24. package/bin/webui/fixtures/knowledge.js +7 -1
  25. package/bin/webui/fixtures/stats.js +16 -0
  26. package/bin/webui/i18n/en/behaviour.json +143 -0
  27. package/bin/webui/i18n/en/nav.json +25 -24
  28. package/bin/webui/i18n/en/tour.json +37 -35
  29. package/bin/webui/i18n/id/behaviour.json +143 -0
  30. package/bin/webui/i18n/id/nav.json +25 -24
  31. package/bin/webui/i18n/id/tour.json +37 -35
  32. package/bin/webui/js/01-i18n.js +155 -154
  33. package/bin/webui/js/90-tour.js +498 -494
  34. package/bin/webui/js/91-shortcuts.js +126 -126
  35. package/bin/webui/js/99-boot.js +121 -118
  36. package/bin/webui/js/panels/behaviour.js +1022 -0
  37. package/mock-run/INDEX.md +109 -107
  38. package/mock-run/gotcha-import.md +118 -0
  39. package/mock-run/habits.md +129 -0
  40. package/mock-run/orc-quick.md +6 -1
  41. package/package.json +1 -1
  42. package/templates/agents/MODEL-MAPPING.md +7 -7
  43. package/templates/agents/orc-advisor-opus-5-xhigh.md +1 -7
  44. package/templates/agents/orc-analyze-mini-opus-5-med.md +1 -6
  45. package/templates/agents/orc-analyze-mini-sonnet-5-high.md +1 -4
  46. package/templates/agents/orc-claude-writer-opus-4-8-high.md +48 -53
  47. package/templates/agents/orc-claude-writer-opus-5-med.md +1 -8
  48. package/templates/agents/orc-context-combiner-opus-5-high.md +1 -11
  49. package/templates/agents/orc-executor-haiku-4-5.md +14 -6
  50. package/templates/agents/orc-executor-opus-4-7-high.md +14 -6
  51. package/templates/agents/orc-executor-opus-4-7-med.md +14 -6
  52. package/templates/agents/orc-executor-opus-4-8-high.md +14 -6
  53. package/templates/agents/orc-executor-opus-5-high.md +14 -6
  54. package/templates/agents/orc-executor-opus-5-low.md +14 -6
  55. package/templates/agents/orc-executor-opus-5-med.md +14 -6
  56. package/templates/agents/orc-executor-sonnet-4-6-high.md +14 -6
  57. package/templates/agents/orc-executor-sonnet-4-6-med.md +14 -6
  58. package/templates/agents/orc-executor-sonnet-5-high.md +14 -6
  59. package/templates/agents/orc-graph-noter-sonnet-4-6-med.md +1 -10
  60. package/templates/agents/orc-judge-opus-5-xhigh.md +5 -9
  61. package/templates/agents/orc-learn-writer-opus-5-low.md +1 -7
  62. package/templates/agents/orc-pattern-codifier-opus-5-med.md +1 -8
  63. package/templates/agents/orc-pattern-codifier-sonnet-5-high.md +58 -63
  64. package/templates/agents/orc-planner-mini-opus-5-med.md +1 -4
  65. package/templates/agents/orc-planner-mini-sonnet-5-high.md +1 -2
  66. package/templates/agents/orc-planner-opus-5-med.md +1 -4
  67. package/templates/agents/orc-recon-opus-5-low.md +1 -8
  68. package/templates/agents/orc-recon-sonnet-4-6-med.md +1 -8
  69. package/templates/agents/orc-retro-opus-5-med.md +6 -8
  70. package/templates/agents/orc-retro-sonnet-5-high.md +6 -7
  71. package/templates/agents/orc-reviewer-opus-5-med.md +52 -16
  72. package/templates/agents/orc-scout-opus-5-low.md +1 -6
  73. package/templates/agents/orc-scout-sonnet-4-6-high.md +35 -39
  74. package/templates/agents/orc-system-analyst-opus-5-high.md +1 -6
  75. package/templates/agents/orc-test-author-opus-5-med.md +4 -5
  76. package/templates/agents/orc-trace-writer-haiku-4-5.md +3 -7
  77. package/templates/agents/orc-verifier-opus-5-med.md +16 -8
  78. package/templates/agents/orc-wiki-scanner-opus-4-8-high.md +74 -79
  79. package/templates/agents/orc-wiki-scanner-opus-5-med.md +1 -8
  80. package/templates/agents/orc-wiki-scanner-sonnet-5-high.md +97 -106
  81. package/templates/commands/orc-analyze.md +13 -21
  82. package/templates/commands/orc-fast.md +10 -15
  83. package/templates/commands/orc-poly.md +12 -21
  84. package/templates/commands/orc-pr-driver.md +11 -30
  85. package/templates/commands/orc-pr-setup.md +10 -31
  86. package/templates/commands/orc-route.md +11 -41
  87. package/templates/commands/orc-test.md +5 -60
  88. package/templates/hooks/README.md +34 -0
  89. package/templates/hooks/orc-session-hook.js +264 -0
  90. package/templates/hooks/orc-statusline.js +3 -1
  91. package/templates/skills/_shared/README.md +9 -0
  92. package/templates/skills/_shared/code-graph.md +47 -55
  93. package/templates/skills/_shared/config-precedence.md +3 -1
  94. package/templates/skills/_shared/extra-dispatch.md +73 -88
  95. package/templates/skills/_shared/gotchas.md +228 -177
  96. package/templates/skills/_shared/habits.md +101 -0
  97. package/templates/skills/_shared/lane-contract.md +84 -0
  98. package/templates/skills/_shared/phases/README.md +142 -83
  99. package/templates/skills/_shared/phases/analyst-gates.md +10 -21
  100. package/templates/skills/_shared/phases/execution.md +8 -14
  101. package/templates/skills/_shared/phases/house-rules.md +27 -32
  102. package/templates/skills/_shared/phases/intake.md +127 -133
  103. package/templates/skills/_shared/phases/mock-example.md +46 -56
  104. package/templates/skills/_shared/phases/plan-handoff.md +91 -97
  105. package/templates/skills/_shared/phases/planning.md +7 -17
  106. package/templates/skills/_shared/phases/preflight.md +19 -42
  107. package/templates/skills/_shared/phases/review.md +23 -27
  108. package/templates/skills/_shared/phases/rules.md +18 -42
  109. package/templates/skills/_shared/phases/scoring.md +55 -65
  110. package/templates/skills/_shared/phases/security-checklist.md +46 -50
  111. package/templates/skills/_shared/phases/security.md +45 -55
  112. package/templates/skills/_shared/phases/ship.md +6 -15
  113. package/templates/skills/_shared/phases/stop-resume.md +2 -5
  114. package/templates/skills/_shared/phases/summary.md +73 -48
  115. package/templates/skills/_shared/phases/testgen.md +41 -51
  116. package/templates/skills/_shared/phases/trace-verbs.md +433 -0
  117. package/templates/skills/_shared/phases/trace.md +136 -367
  118. package/templates/skills/_shared/phases/verify.md +62 -70
  119. package/templates/skills/_shared/phases/wave-grouping.md +128 -133
  120. package/templates/skills/_shared/phases/wiki-consult.md +10 -6
  121. package/templates/skills/_shared/read-ladder.md +2 -55
  122. package/templates/skills/_shared/return-validation.md +17 -70
  123. package/templates/skills/_shared/review-slice.md +79 -0
  124. package/templates/skills/_shared/smoke-gate.md +46 -28
  125. package/templates/skills/context-combiner/SKILL.md +15 -44
  126. package/templates/skills/orc/SKILL.md +34 -62
  127. package/templates/skills/orc/references/pattern-gate.md +89 -89
  128. package/templates/skills/orc/references/phases/intake.md +41 -47
  129. package/templates/skills/orc/references/phases/integration.md +13 -19
  130. package/templates/skills/orc/references/preflight-report.md +8 -9
  131. package/templates/skills/orc/references/ultra-mode.md +8 -6
  132. package/templates/skills/orc/subskills/orc-execution/SKILL.md +27 -73
  133. package/templates/skills/orc/subskills/orc-execution/core.md +12 -99
  134. package/templates/skills/orc/subskills/orc-execution/subagent.md +14 -13
  135. package/templates/skills/orc/subskills/orc-review-verify/SKILL.md +11 -52
  136. package/templates/skills/orc/subskills/orc-review-verify/core.md +52 -135
  137. package/templates/skills/orc/subskills/orc-review-verify/subagent.md +7 -7
  138. package/templates/skills/orc/subskills/orc-testgen/SKILL.md +11 -22
  139. package/templates/skills/orc/subskills/orc-testgen/core.md +20 -59
  140. package/templates/skills/orc/subskills/orc-testgen/subagent.md +7 -7
  141. package/templates/skills/orc-advisor/SKILL.md +56 -60
  142. package/templates/skills/orc-analyze/SKILL.md +30 -66
  143. package/templates/skills/orc-analyze/schemas/report-audit.md +2 -1
  144. package/templates/skills/orc-analyze/schemas/report-prose.md +2 -1
  145. package/templates/skills/orc-analyze-mini/SKILL.md +35 -70
  146. package/templates/skills/orc-diy/README.md +31 -0
  147. package/templates/skills/orc-diy/SKILL.md +23 -74
  148. package/templates/skills/orc-diy/references/blocks/pattern.md +18 -18
  149. package/templates/skills/orc-fast/SKILL.md +44 -72
  150. package/templates/skills/orc-judge/SKILL.md +77 -82
  151. package/templates/skills/orc-mini/SKILL.md +61 -109
  152. package/templates/skills/orc-pattern/SKILL.md +27 -48
  153. package/templates/skills/orc-poly/SKILL.md +32 -61
  154. package/templates/skills/orc-pr-driver/SKILL.md +25 -51
  155. package/templates/skills/orc-pr-driver/references/green-gate.md +113 -105
  156. package/templates/skills/orc-pr-setup/SKILL.md +20 -45
  157. package/templates/skills/orc-quick/README.md +43 -2
  158. package/templates/skills/orc-quick/SKILL.md +76 -107
  159. package/templates/skills/orc-quick/references/dispatch-gate.md +16 -5
  160. package/templates/skills/orc-quick/references/gh-mode.md +48 -1
  161. package/templates/skills/orc-quick/references/look.md +3 -1
  162. package/templates/skills/orc-retro/SKILL.md +19 -18
  163. package/templates/skills/orc-retro/examples/retro-mock.md +1 -1
  164. package/templates/skills/orc-route/SKILL.md +25 -45
  165. package/templates/skills/orc-test/SKILL.md +16 -37
  166. package/templates/skills/orc-verify/SKILL.md +14 -32
  167. package/templates/skills/orc-wait/SKILL.md +156 -163
  168. package/templates/skills/orc-wiki/references/phases/phase-0.md +1 -6
  169. package/templates/skills/orc-wiki/references/phases/phase-1.md +1 -6
  170. package/templates/skills/orc-wiki/references/phases/phase-2.md +1 -6
  171. package/templates/skills/orc-wiki/references/phases/phase-3.md +1 -6
  172. package/templates/skills/orc-wiki/references/phases/phase-3c.md +1 -6
@@ -4,12 +4,9 @@ description: >
4
4
  Run the test against the real running system, and report only what was
5
5
  observed. Use for "/orc-test", "test my API end to end", "run the endpoints
6
6
  from happy path to security", "test this against staging", "e2e the login
7
- flow". It brings the local system up (and STOPS and hands back if it will
8
- not come up), finds the surface, digs the repo for the flow from the first
9
- request into the target endpoint, expands the case matrix from happy path to
10
- edge to abuse to security, RUNS every case, and writes the evidence and the
11
- report into orc/orc-test/<slug>/. It never edits the system it is testing,
12
- never commits, and never reports a result it did not observe.
7
+ flow". It brings the system up, expands the cases from happy path to security,
8
+ RUNS every case, and writes the evidence and the report into
9
+ orc/orc-test/<slug>/. It never edits the system it tests and never commits.
13
10
  ---
14
11
 
15
12
  # `/orc-test` — the lane that RUNS the test
@@ -172,26 +169,15 @@ Canonical contract: `../_shared/live-target.md`. Read it before phase T1.
172
169
  and offer: re-run a tier · widen the surface · `/orc-pact` the invariant this
173
170
  run proved · `/orc-challenge` the report. Never proceed on your own.
174
171
 
175
- ## Config
172
+ ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
176
173
 
177
- **ONE resolver, and it is not you:** `orc lane config orc-test --json`. Obey
178
- `effective`, print every line in `announce[]` VERBATIM at preflight, and honour
179
- `stops[]` before the first case runs. Never re-derive a value, a precedence or
180
- an inertness from `.claude/orc.config.yaml` — a key this lane does not read is
181
- not in the answer, and a key another key shadows comes back already marked.
182
- Exit ≠ 0 → say the CLI is unavailable and fall back to
183
- `../_shared/config-precedence.md`'s documented defaults, out loud. Priorities
184
- and families: `../_shared/config-precedence.md`.
185
-
186
- ## Calls
187
-
188
- **ONE catalogue, and it is not you:** `orc lane calls orc-test --json` names
189
- every CLI call this lane makes, each with its exit-code contract, its cost, when
190
- to run it, and what an EMPTY answer means. Never invent a spelling, never
191
- re-word an exit code, and never re-derive a state word — the CLI's state words
192
- are the only state words, and **an exit code is an ANSWER wherever that contract
193
- says so, not a failure**. A call the answer does not name is a call this lane
194
- does not make.
174
+ - **Calls:** `orc lane calls orc-test --json` names every call and its exit codes.
175
+ **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
176
+ - **Config:** `orc lane config orc-test --json`. Obey `effective`, print every line
177
+ in `announce[]` VERBATIM at preflight, and honour `stops[]` before the first case runs.
178
+ Never merge `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).
179
+ - **Rules:** `orc rules slice --lane orc-test --json` is the ONLY assembler
180
+ (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
195
181
 
196
182
  ## Sending work off Claude (`orc extra`)
197
183
 
@@ -223,18 +209,11 @@ behind the disk. Keep the `Where it stands:` line at column 0.
223
209
 
224
210
  ## Trace
225
211
 
226
- Tier **Iterative** — one packet per completed cycle. Narration is DISPATCHED,
227
- never remembered: build the PHASE PACKET and dispatch
228
- `orc-trace-writer-haiku-4-5`. Canonical: `../_shared/phases/trace.md`.
229
-
230
- ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
231
-
232
- `orc rules slice --lane orc-test --json` is the ONLY assembler; never build
233
- the card here. It rides under the house rules and above the task —
234
- **house rules > your project's rules > ORC's own packs** — and its `line` prints
235
- VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
236
- never a silent choice) and `rules_overridden[]`.
212
+ Tier **Iterative** — one packet per completed cycle. Pipe the PHASE PACKET to
213
+ `orc trace write --packet -` (exit ≠ 0 → `orc-trace-writer-haiku-4-5`).
214
+ Canonical: `../_shared/phases/trace.md`.
215
+
237
216
  ## Waiting mid-run (`/orc-wait`)
238
217
 
239
218
  Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
240
- Checkpoint **cycle** · safe point **case boundary**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait mid-request — a long `orc test run` is the first ORC operation that takes minutes with no model in it, and the safe point is BETWEEN cases.
219
+ Checkpoint **cycle** · safe point **case boundary**. Never begin a wait mid-request — a long `orc test run` is the first ORC operation that takes minutes with no model in it, and the safe point is BETWEEN cases.
@@ -64,13 +64,11 @@ Verdict: <READY / NEEDS FIXES>
64
64
 
65
65
  ## Behavior trace (always on)
66
66
 
67
- `../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
68
- the file and the layers). Lane token `verify`, tier **Single-dispatch** —
69
- exactly ONE end-of-run packet, dispatched solo before `.current` is deleted.
70
- At run start write `log_dir/.current` = `run-verify-<slug>-<DDMMYY>-<HHMMSS>.txt` AND
71
- `touch the trace file` of that name in the SAME step.
72
- Nothing else about the protocol is restated here; a phase that ends with
73
- `zero new trace lines is a protocol violation`.
67
+ `../_shared/phases/trace.md` (`core`, at run start; `orc lane phases orc-verify --json` →
68
+ `trace_grammar` gives the verbs). Lane token `verify`, tier
69
+ **Single-dispatch**. At run start write `log_dir/.current` =
70
+ `run-verify-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
71
+ in the SAME step. A phase that ends with `zero new trace lines is a protocol violation`.
74
72
 
75
73
  ## Boundaries
76
74
 
@@ -80,33 +78,17 @@ Nothing else about the protocol is restated here; a phase that ends with
80
78
  - Reminder: to see usage limits, tell the user to run `/usage` (never invoke it
81
79
  programmatically).
82
80
 
83
- ## Config
81
+ ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
84
82
 
85
- Resolve with `orc lane config orc-verify --json` and obey `effective`. Never merge
86
- `.claude/orc.config.yaml` yourself, and never re-derive a precedence. Exit ≠ 0 →
87
- say so and use `../_shared/config-precedence.md`'s documented defaults, out
88
- loud. Nothing this lane reads is contested, gated or a stop, so it owes no
89
- preflight line and has no gate to honour.
83
+ - **Calls:** `orc lane calls orc-verify --json` names every call and its exit codes.
84
+ **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
85
+ - **Config:** `orc lane config orc-verify --json`. Obey `effective`. Never merge
86
+ `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`). Nothing
87
+ here is contested, gated or a stop: no preflight line, no gate to honour.
88
+ - **Rules:** `orc rules slice --lane orc-verify --json` is the ONLY assembler
89
+ (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
90
90
 
91
- ## Calls
92
-
93
- **ONE catalogue, and it is not you:** `orc lane calls orc-verify --json` names every
94
- CLI call this lane makes, each with its exit-code contract, its cost, when to run
95
- it, and what an EMPTY answer means. Never invent a spelling, never re-word an
96
- exit code, and never re-derive a state word — the CLI's state words are the only
97
- state words, and **an exit code is an ANSWER wherever that contract says so, not
98
- a failure**. A call the answer does not name is a call this lane does not make.
99
- Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
100
- command you are about to run, out loud, before running it.
101
-
102
- ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
103
-
104
- `orc rules slice --lane orc-verify --json` is the ONLY assembler; never build
105
- the card here. It rides under the house rules and above the task —
106
- **house rules > your project's rules > ORC's own packs** — and its `line` prints
107
- VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
108
- never a silent choice) and `rules_overridden[]`.
109
91
  ## Waiting mid-run (`/orc-wait`)
110
92
 
111
93
  Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
112
- Checkpoint **none** · safe point **single dispatch**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.
94
+ Checkpoint **none** · safe point **single dispatch**.
@@ -1,163 +1,156 @@
1
- ---
2
- name: orc-wait
3
- description: >
4
- Wait for wall-clock time to pass without losing the run you are in. Use for
5
- "/orc-wait", "/orc-wait 30", "/orc-wait 2h hard", "wait for my quota to
6
- reset", "pause this until the window resets". You watched the statusline, you
7
- saw the window was almost full, and you decided to stop — this carries that
8
- decision out: it writes the hand-back, waits in short detached hops that cost
9
- ZERO tokens, and picks the run back up where it left it. Three modes decide
10
- how much finishes before it stops: safe (finish the wave), soft (stop now, but
11
- force the checkpoint first), hard (stop now, RESUME.md only, can lose work).
12
- Also carries the veto — "/orc-wait block <reason>" tells ORC not to stop you
13
- at all. It never dispatches an agent, never runs another lane, and never
14
- writes your config.
15
- ---
16
-
17
- # ORC — the wait
18
-
19
- Canonical contract: **`_shared/wait.md`**. Load it before you do anything here.
20
- This spine is the entry point; that file is the rule.
21
-
22
- > **`a lane that waits without a hand-back` has broken this contract.**
23
-
24
- A wait is a stop. Every stop writes its hand-back BEFORE it ends, because the
25
- thing that resumes the run may not be this session.
26
-
27
- ## What this lane never does
28
-
29
- - It never dispatches an agent to do the waiting. An agent runs on the same
30
- account and burns the window the wait exists to protect.
31
- - It never runs another lane, and never changes the work: same tasks, same
32
- slice, same agent resolve after the wait as before it.
33
- - It never writes the user's config.
34
- - It never computes hops itself. `orc wait plan` does that.
35
- - It is **command-entry only.** No lane invokes `/orc-wait` for itself.
36
-
37
- ## W1 — parse (silent)
38
-
39
- Run `orc wait plan <spec> --json`. Never do this arithmetic in your head.
40
-
41
- | exit | meaning | what you do |
42
- |---|---|---|
43
- | 0 | planned | go to W2 |
44
- | 1 | unparsable | show the `hint` verbatim and STOP. Do not guess a duration. |
45
- | 2 | no reading | show the `hint` verbatim and STOP. `reset` needs a usage reading; ask for a time instead. |
46
-
47
- `block` / `unblock` skip W1 entirely — see **The veto** below.
48
-
49
- ## W2 — resolve the mode
50
-
51
- A named mode always wins. With none, read `wait_default_mode`:
52
-
53
- - `ask` (the default) → ask, in ONE turn, with the cost of each spelled out:
54
-
55
- ```
56
- Which mode?
57
- 1. safe — finish the current wave first, then wait. Loses nothing.
58
- 2. soft — stop at the next turn. Forces the checkpoint first.
59
- 3. hard — stop at the next turn. No checkpoint. Can lose the wave.
60
- ```
61
- - `safe` | `soft` | `hard` → use it, and say which one you used and why.
62
-
63
- If `orc wait lanes --json` reports `modes_differ: false` for the lane in flight
64
- (nothing to checkpoint), SAY SO and do not ask — the three modes are identical
65
- there, and asking a question with one real answer wastes a turn.
66
-
67
- ## W3 — reach the stop point
68
-
69
- Answer the user IMMEDIATELY, before you reach it. A queued command that looks
70
- ignored reads as a broken command.
71
-
72
- ```
73
- ⏸ I got your wait. 30 minutes, soft.
74
- Wave 3 is running. I do not stop a dispatch in the middle.
75
- I stop as soon as wave 3's returns are validated.
76
- ```
77
-
78
- | mode | stop at |
79
- |---|---|
80
- | `safe` | the next SAFE POINT — see the table in `_shared/wait.md` |
81
- | `soft` | the next model turn |
82
- | `hard` | the next model turn |
83
-
84
- **Never begin a wait** between a dispatch and its validated return, inside the
85
- stop sequence, during a file write, or before the smoke gate has reported. That
86
- holds in every mode, `hard` included.
87
-
88
- Never write "immediately". `hard` stops at the first moment ORC can act.
89
-
90
- ## W4 — hand back (the step that is never skipped)
91
-
92
- | mode | what you write |
93
- |---|---|
94
- | `safe`, `soft` | the FULL stop sequence — `_shared/phases/stop-resume.md`, steps 2–3b |
95
- | `hard` | `RESUME.md` ONLY, with your own hand, never a dispatched agent |
96
-
97
- **`soft` is FORCED.** If the checkpoint write fails, **do not stop**. Report the
98
- failure and stay in the run. Stopping without a good checkpoint is the one thing
99
- that loses work.
100
-
101
- `hard` is the dispatch-free stop: it writes only what ORC can write itself, and
102
- that is exactly why it is fast. When you use it, name what may be lost:
103
-
104
- ```
105
- ⚠ hard: wave 3 had 2 dispatches in flight. Their file writes may still land,
106
- but their returns are not validated. RESUME.md records this.
107
- ```
108
-
109
- ## W5 — hop
110
-
111
- Run each hop as a **detached** command so no model is running and no tokens are
112
- spent. One hop per entry in `hops[]` from W1.
113
-
114
- After every hop:
115
-
116
- 1. `orc usage check --json` (exit 0 → the window recovered; go to W6)
117
- 2. `orc wait status --json` — `cancel_requested: true` → stop hopping, go to W6
118
- 3. otherwise, the next hop
119
-
120
- Print the END TIME every hop, not only the length: "hop 2 of 4, ends 19:14".
121
- A user who cannot see when a wait ends cannot tell it from a hang.
122
-
123
- ## W6 — come back
124
-
125
- Read `context` from `orc usage check --json`.
126
-
127
- - **context small** → continue the run here, in one line.
128
- - **context large** → STOP. Offer both paths, and recommend the fresh session:
129
-
130
- ```
131
- The wait ended. usage: 5h 9% (4h51m) · context: 81%
132
-
133
- Context is large, and the prompt cache expired during the wait.
134
- → new session, then: orc resume <slug>
135
- Or reply `continue` to go on here.
136
- ```
137
-
138
- ORC cannot clear its own context — `/clear` is the user's action. Offer the
139
- swap; never claim to have performed it.
140
-
141
- ## The veto — `block` and `unblock`
142
-
143
- `/orc-wait block <reason>` → `orc wait block <slug> --reason "<why>"`.
144
-
145
- - The CLI writes it. You never write `wait.json` yourself.
146
- - **The reason is required.** Exit 1 means you must ask for one — relay the
147
- refusal, never invent a reason on the user's behalf.
148
- - It suppresses what ORC COMPUTES, never what the user TYPES. A typed
149
- `/orc-wait 30 hard` still waits while a block is active.
150
- - Re-announce it, with its age, at EVERY gate it suppresses. There is no
151
- auto-expiry.
152
-
153
- `orc wait cancel` is a DIFFERENT thing: it ends a wait already running. Block is
154
- before, cancel is during. Never present them as the same choice.
155
-
156
- ## Trace
157
-
158
- The CLI writes the `WAIT` lines itself, into the trace already open. You do not
159
- narrate them and you do not repeat them.
160
-
161
- `/orc-wait` opens no run, so it is **not a lane** in the trace enum and writes
162
- no `run-<lane>-<slug>` pointer — the `/orc-explain` precedent. With no run in
163
- flight, a wait is simply a wait and nothing is traced.
1
+ ---
2
+ name: orc-wait
3
+ description: >
4
+ Wait for wall-clock time to pass without losing the run you are in. Use for
5
+ "/orc-wait", "/orc-wait 30", "/orc-wait 2h hard", "wait for my quota to
6
+ reset", "pause this until the window resets". It writes the hand-back, waits
7
+ in detached hops that cost ZERO tokens, and picks the run back up. Modes: safe
8
+ (finish the wave), soft (checkpoint, then stop), hard (stop now). "/orc-wait
9
+ block <reason>" is the veto.
10
+ ---
11
+
12
+ # ORC — the wait
13
+
14
+ Canonical contract: **`_shared/wait.md`**. Load it before you do anything here.
15
+ This spine is the entry point; that file is the rule.
16
+
17
+ > **`a lane that waits without a hand-back` has broken this contract.**
18
+
19
+ A wait is a stop. Every stop writes its hand-back BEFORE it ends, because the
20
+ thing that resumes the run may not be this session.
21
+
22
+ ## What this lane never does
23
+
24
+ - It never dispatches an agent to do the waiting. An agent runs on the same
25
+ account and burns the window the wait exists to protect.
26
+ - It never runs another lane, and never changes the work: same tasks, same
27
+ slice, same agent resolve after the wait as before it.
28
+ - It never writes the user's config.
29
+ - It never computes hops itself. `orc wait plan` does that.
30
+ - It is **command-entry only.** No lane invokes `/orc-wait` for itself.
31
+
32
+ ## W1 — parse (silent)
33
+
34
+ Run `orc wait plan <spec> --json`. Never do this arithmetic in your head.
35
+
36
+ | exit | meaning | what you do |
37
+ |---|---|---|
38
+ | 0 | planned | go to W2 |
39
+ | 1 | unparsable | show the `hint` verbatim and STOP. Do not guess a duration. |
40
+ | 2 | no reading | show the `hint` verbatim and STOP. `reset` needs a usage reading; ask for a time instead. |
41
+
42
+ `block` / `unblock` skip W1 entirely — see **The veto** below.
43
+
44
+ ## W2 — resolve the mode
45
+
46
+ A named mode always wins. With none, read `wait_default_mode`:
47
+
48
+ - `ask` (the default) → ask, in ONE turn, with the cost of each spelled out:
49
+
50
+ ```
51
+ Which mode?
52
+ 1. safe — finish the current wave first, then wait. Loses nothing.
53
+ 2. soft — stop at the next turn. Forces the checkpoint first.
54
+ 3. hard — stop at the next turn. No checkpoint. Can lose the wave.
55
+ ```
56
+ - `safe` | `soft` | `hard` → use it, and say which one you used and why.
57
+
58
+ If `orc wait lanes --json` reports `modes_differ: false` for the lane in flight
59
+ (nothing to checkpoint), SAY SO and do not ask — the three modes are identical
60
+ there, and asking a question with one real answer wastes a turn.
61
+
62
+ ## W3 — reach the stop point
63
+
64
+ Answer the user IMMEDIATELY, before you reach it. A queued command that looks
65
+ ignored reads as a broken command.
66
+
67
+ ```
68
+ ⏸ I got your wait. 30 minutes, soft.
69
+ Wave 3 is running. I do not stop a dispatch in the middle.
70
+ I stop as soon as wave 3's returns are validated.
71
+ ```
72
+
73
+ | mode | stop at |
74
+ |---|---|
75
+ | `safe` | the next SAFE POINT — see the table in `_shared/wait.md` |
76
+ | `soft` | the next model turn |
77
+ | `hard` | the next model turn |
78
+
79
+ **Never begin a wait** between a dispatch and its validated return, inside the
80
+ stop sequence, during a file write, or before the smoke gate has reported. That
81
+ holds in every mode, `hard` included.
82
+
83
+ ## W4 — hand back (the step that is never skipped)
84
+
85
+ | mode | what you write |
86
+ |---|---|
87
+ | `safe`, `soft` | the FULL stop sequence — `_shared/phases/stop-resume.md`, steps 2–3b |
88
+ | `hard` | `RESUME.md` ONLY, with your own hand, never a dispatched agent |
89
+
90
+ **`soft` is FORCED.** If the checkpoint write fails, **do not stop**. Report the
91
+ failure and stay in the run. Stopping without a good checkpoint is the one thing
92
+ that loses work.
93
+
94
+ `hard` is the dispatch-free stop: it writes only what ORC can write itself, and
95
+ that is exactly why it is fast. When you use it, name what may be lost:
96
+
97
+ ```
98
+ ⚠ hard: wave 3 had 2 dispatches in flight. Their file writes may still land,
99
+ but their returns are not validated. RESUME.md records this.
100
+ ```
101
+
102
+ ## W5 — hop
103
+
104
+ Run each hop as a **detached** command so no model is running and no tokens are
105
+ spent. One hop per entry in `hops[]` from W1.
106
+
107
+ After every hop:
108
+
109
+ 1. `orc usage check --json` (exit 0 → the window recovered; go to W6)
110
+ 2. `orc wait status --json` — `cancel_requested: true` → stop hopping, go to W6
111
+ 3. otherwise, the next hop
112
+
113
+ Print the END TIME every hop, not only the length: "hop 2 of 4, ends 19:14".
114
+ A user who cannot see when a wait ends cannot tell it from a hang.
115
+
116
+ ## W6 — come back
117
+
118
+ Read `context` from `orc usage check --json`.
119
+
120
+ - **context small** → continue the run here, in one line.
121
+ - **context large** → STOP. Offer both paths (H `any.stop.where`), and recommend the fresh session:
122
+
123
+ ```
124
+ The wait ended. usage: 5h 9% (4h51m) · context: 81%
125
+
126
+ Context is large, and the prompt cache expired during the wait.
127
+ → new session, then: orc resume <slug>
128
+ Or reply `continue` to go on here.
129
+ ```
130
+
131
+ **Habits:** the run in flight had `habits{}` in its config answer → read
132
+ `../_shared/habits.md`; its next packet takes the `ASK`. No `habits{}` → ignore `(H …)`.
133
+
134
+ ## The veto — `block` and `unblock`
135
+
136
+ `/orc-wait block <reason>` → `orc wait block <slug> --reason "<why>"`.
137
+
138
+ - The CLI writes it. You never write `wait.json` yourself.
139
+ - **The reason is required.** Exit 1 means you must ask for one — relay the
140
+ refusal, never invent a reason on the user's behalf.
141
+ - It suppresses what ORC COMPUTES, never what the user TYPES. A typed
142
+ `/orc-wait 30 hard` still waits while a block is active.
143
+ - Re-announce it, with its age, at EVERY gate it suppresses. There is no
144
+ auto-expiry.
145
+
146
+ `orc wait cancel` is a DIFFERENT thing: it ends a wait already running. Block is
147
+ before, cancel is during. Never present them as the same choice.
148
+
149
+ ## Trace
150
+
151
+ The CLI writes the `WAIT` lines itself, into the trace already open. You do not
152
+ narrate them and you do not repeat them.
153
+
154
+ `/orc-wait` opens no run, so it is **not a lane** in the trace enum and writes
155
+ no `run-<lane>-<slug>` pointer — the `/orc-explain` precedent. With no run in
156
+ flight, a wait is simply a wait and nothing is traced.
@@ -1,11 +1,6 @@
1
1
  # Phase — Phase 0 — Entry & auto-branch (on /orc-wiki) (id: `phase-0`)
2
2
 
3
- > **`/orc-wiki` phase file.** Moved out of `orc-wiki/SKILL.md` at v1.0.0 W14. The
4
- > spine is loaded IN FULL when the skill activates; this is loaded when the phase
5
- > fires — and a wiki run reaches FEW of them: Phase 0 auto-branches into fresh /
6
- > resume / refresh / repair, and Phase 3c is a legacy backfill. ONE consumer, so
7
- > it stays in this lane (`../../../_shared/phases/README.md`: a file with one
8
- > consumer stays home). `orc lane phases orc-wiki --json` names the file.
3
+ > **`/orc-wiki` phase file** — read when the phase fires; a wiki run reaches few of them. One consumer, so it stays home. `orc lane phases orc-wiki --json` names the file.
9
4
 
10
5
  <!-- orc:layer full -->
11
6
 
@@ -1,11 +1,6 @@
1
1
  # Phase — Phase 1 — Area planning (after consent) (id: `phase-1`)
2
2
 
3
- > **`/orc-wiki` phase file.** Moved out of `orc-wiki/SKILL.md` at v1.0.0 W14. The
4
- > spine is loaded IN FULL when the skill activates; this is loaded when the phase
5
- > fires — and a wiki run reaches FEW of them: Phase 0 auto-branches into fresh /
6
- > resume / refresh / repair, and Phase 3c is a legacy backfill. ONE consumer, so
7
- > it stays in this lane (`../../../_shared/phases/README.md`: a file with one
8
- > consumer stays home). `orc lane phases orc-wiki --json` names the file.
3
+ > **`/orc-wiki` phase file** — read when the phase fires; a wiki run reaches few of them. One consumer, so it stays home. `orc lane phases orc-wiki --json` names the file.
9
4
 
10
5
  <!-- orc:layer full -->
11
6
 
@@ -1,11 +1,6 @@
1
1
  # Phase — Phase 2 — Scan (spawned agents, 5-task pauses) (id: `phase-2`)
2
2
 
3
- > **`/orc-wiki` phase file.** Moved out of `orc-wiki/SKILL.md` at v1.0.0 W14. The
4
- > spine is loaded IN FULL when the skill activates; this is loaded when the phase
5
- > fires — and a wiki run reaches FEW of them: Phase 0 auto-branches into fresh /
6
- > resume / refresh / repair, and Phase 3c is a legacy backfill. ONE consumer, so
7
- > it stays in this lane (`../../../_shared/phases/README.md`: a file with one
8
- > consumer stays home). `orc lane phases orc-wiki --json` names the file.
3
+ > **`/orc-wiki` phase file** — read when the phase fires; a wiki run reaches few of them. One consumer, so it stays home. `orc lane phases orc-wiki --json` names the file.
9
4
 
10
5
  <!-- orc:layer full -->
11
6
 
@@ -1,11 +1,6 @@
1
1
  # Phase — Phase 3 — Assemble & inject (id: `phase-3`)
2
2
 
3
- > **`/orc-wiki` phase file.** Moved out of `orc-wiki/SKILL.md` at v1.0.0 W14. The
4
- > spine is loaded IN FULL when the skill activates; this is loaded when the phase
5
- > fires — and a wiki run reaches FEW of them: Phase 0 auto-branches into fresh /
6
- > resume / refresh / repair, and Phase 3c is a legacy backfill. ONE consumer, so
7
- > it stays in this lane (`../../../_shared/phases/README.md`: a file with one
8
- > consumer stays home). `orc lane phases orc-wiki --json` names the file.
3
+ > **`/orc-wiki` phase file** — read when the phase fires; a wiki run reaches few of them. One consumer, so it stays home. `orc lane phases orc-wiki --json` names the file.
9
4
 
10
5
  <!-- orc:layer full -->
11
6
 
@@ -1,11 +1,6 @@
1
1
  # Phase — Phase 3c — CROSSLINK-ONLY (legacy backfill: publish/resolve, NO area scan) (id: `phase-3c`)
2
2
 
3
- > **`/orc-wiki` phase file.** Moved out of `orc-wiki/SKILL.md` at v1.0.0 W14. The
4
- > spine is loaded IN FULL when the skill activates; this is loaded when the phase
5
- > fires — and a wiki run reaches FEW of them: Phase 0 auto-branches into fresh /
6
- > resume / refresh / repair, and Phase 3c is a legacy backfill. ONE consumer, so
7
- > it stays in this lane (`../../../_shared/phases/README.md`: a file with one
8
- > consumer stays home). `orc lane phases orc-wiki --json` names the file.
3
+ > **`/orc-wiki` phase file** — read when the phase fires; a wiki run reaches few of them. One consumer, so it stays home. `orc lane phases orc-wiki --json` names the file.
9
4
 
10
5
  <!-- orc:layer full -->
11
6