@azure-id/orc 0.56.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (153) hide show
  1. package/CHANGELOG.md +228 -0
  2. package/README-id.md +143 -53
  3. package/README.md +124 -103
  4. package/bin/build-agents.js +18 -11
  5. package/bin/cli.js +4139 -315
  6. package/bin/onboarding-content.js +0 -3
  7. package/bin/test-run.js +491 -0
  8. package/bin/verify-contracts.js +4256 -3277
  9. package/bin/verify-package.js +563 -498
  10. package/bin/webui/api.js +1186 -1163
  11. package/bin/webui/app.html +9 -0
  12. package/bin/webui/css/06-responsive.css +120 -108
  13. package/bin/webui/css/panels/extra.css +29 -0
  14. package/bin/webui/css/panels/lanes.css +134 -0
  15. package/bin/webui/css/panels/settings.css +79 -3
  16. package/bin/webui/fixtures/extra.js +2036 -1934
  17. package/bin/webui/fixtures/flow.js +2 -2
  18. package/bin/webui/fixtures/index.js +503 -486
  19. package/bin/webui/fixtures/lanes.js +218 -0
  20. package/bin/webui/fixtures/settings.js +261 -34
  21. package/bin/webui/fixtures/stats.js +3 -3
  22. package/bin/webui/i18n/TERMS.md +135 -134
  23. package/bin/webui/i18n/en/extra.json +345 -313
  24. package/bin/webui/i18n/en/lanes.json +29 -0
  25. package/bin/webui/i18n/en/nav.json +1 -0
  26. package/bin/webui/i18n/en/overview.json +2 -0
  27. package/bin/webui/i18n/en/settings.json +16 -5
  28. package/bin/webui/i18n/id/extra.json +345 -313
  29. package/bin/webui/i18n/id/lanes.json +29 -0
  30. package/bin/webui/i18n/id/nav.json +1 -0
  31. package/bin/webui/i18n/id/overview.json +2 -0
  32. package/bin/webui/i18n/id/settings.json +15 -4
  33. package/bin/webui/js/01-i18n.js +1 -0
  34. package/bin/webui/js/panels/extra.js +3199 -3011
  35. package/bin/webui/js/panels/lanes.js +259 -0
  36. package/bin/webui/js/panels/overview.js +10 -0
  37. package/bin/webui/js/panels/settings.js +149 -3
  38. package/package.json +3 -3
  39. package/templates/agents/MODEL-MAPPING.md +23 -35
  40. package/templates/agents/orc-executor-opus-4-7-high.md +1 -1
  41. package/templates/agents/orc-executor-opus-4-7-med.md +1 -1
  42. package/templates/agents/orc-executor-opus-4-8-high.md +1 -1
  43. package/templates/agents/orc-executor-opus-5-high.md +1 -1
  44. package/templates/agents/orc-executor-opus-5-low.md +1 -1
  45. package/templates/agents/orc-executor-opus-5-med.md +1 -1
  46. package/templates/agents/orc-retro-opus-5-med.md +73 -73
  47. package/templates/agents/orc-retro-sonnet-5-high.md +72 -72
  48. package/templates/agents/orc-trace-writer-haiku-4-5.md +107 -107
  49. package/templates/commands/orc-route.md +1 -1
  50. package/templates/commands/orc.md +1 -1
  51. package/templates/skills/_shared/README.md +7 -3
  52. package/templates/skills/_shared/config-precedence.md +198 -0
  53. package/templates/skills/_shared/drift-recovery.md +1 -1
  54. package/templates/skills/_shared/extra-dispatch.md +292 -6
  55. package/templates/skills/_shared/interview.md +1 -1
  56. package/templates/skills/_shared/opus5-only.md +9 -7
  57. package/templates/skills/_shared/phases/README.md +82 -0
  58. package/templates/skills/{orc/references → _shared/phases}/analyst-gates.md +15 -3
  59. package/templates/skills/_shared/phases/execution.md +143 -0
  60. package/templates/skills/{orc/references → _shared/phases}/house-rules.md +13 -1
  61. package/templates/skills/{orc/references → _shared/phases}/intake.md +15 -2
  62. package/templates/skills/_shared/phases/mock-example.md +56 -0
  63. package/templates/skills/{orc/references → _shared/phases}/plan-handoff.md +16 -3
  64. package/templates/skills/_shared/phases/planning.md +135 -0
  65. package/templates/skills/_shared/phases/preflight.md +76 -0
  66. package/templates/skills/_shared/phases/review.md +53 -0
  67. package/templates/skills/_shared/phases/scoring.md +65 -0
  68. package/templates/skills/{orc/references → _shared/phases}/security-checklist.md +12 -1
  69. package/templates/skills/_shared/phases/security.md +55 -0
  70. package/templates/skills/_shared/phases/ship.md +88 -0
  71. package/templates/skills/{orc/references/stop-and-resume.md → _shared/phases/stop-resume.md} +169 -160
  72. package/templates/skills/_shared/phases/summary.md +48 -0
  73. package/templates/skills/_shared/phases/testgen.md +51 -0
  74. package/templates/skills/{orc/references/trace-protocol.md → _shared/phases/trace.md} +49 -6
  75. package/templates/skills/_shared/phases/verify.md +70 -0
  76. package/templates/skills/{orc/references → _shared/phases}/wave-grouping.md +14 -2
  77. package/templates/skills/{orc/references → _shared/phases}/wiki-consult.md +13 -1
  78. package/templates/skills/_shared/read-ladder.md +48 -0
  79. package/templates/skills/context-combiner/SKILL.md +214 -187
  80. package/templates/skills/orc/README.md +148 -150
  81. package/templates/skills/orc/SKILL.md +70 -358
  82. package/templates/skills/orc/config.md +137 -389
  83. package/templates/skills/orc/examples/full-run-mock.md +1 -1
  84. package/templates/skills/orc/references/effort-and-mode.md +16 -18
  85. package/templates/skills/orc/references/phases/intake.md +47 -0
  86. package/templates/skills/orc/references/phases/integration.md +19 -0
  87. package/templates/skills/orc/references/preflight-report.md +4 -4
  88. package/templates/skills/orc/references/ultra-mode.md +117 -123
  89. package/templates/skills/orc/schemas/planning-output.md +279 -279
  90. package/templates/skills/orc/subskills/orc-planner/SKILL.md +260 -264
  91. package/templates/skills/orc/subskills/orc-pr/stack-gate.md +4 -1
  92. package/templates/skills/orc-aftermath/SKILL.md +153 -136
  93. package/templates/skills/orc-analyze/SKILL.md +247 -220
  94. package/templates/skills/orc-analyze/references/branching.md +51 -51
  95. package/templates/skills/orc-analyze/references/thin-input.md +1 -1
  96. package/templates/skills/orc-analyze-mini/SKILL.md +128 -112
  97. package/templates/skills/orc-boundary/SKILL.md +244 -208
  98. package/templates/skills/orc-brainstorm/SKILL.md +372 -339
  99. package/templates/skills/orc-budget/SKILL.md +243 -225
  100. package/templates/skills/orc-challenge/README.md +1 -1
  101. package/templates/skills/orc-challenge/SKILL.md +293 -255
  102. package/templates/skills/orc-challenge/examples/council-full-roster.md +1 -1
  103. package/templates/skills/orc-claude/SKILL.md +216 -199
  104. package/templates/skills/orc-diy/README.md +2 -1
  105. package/templates/skills/orc-diy/SKILL.md +129 -70
  106. package/templates/skills/orc-diy/references/blocks/analyze.md +1 -1
  107. package/templates/skills/orc-diy/references/compile.md +21 -7
  108. package/templates/skills/orc-diy/references/flow-schema.md +2 -2
  109. package/templates/skills/orc-doc/SKILL.md +44 -7
  110. package/templates/skills/orc-explain/SKILL.md +19 -0
  111. package/templates/skills/orc-export/SKILL.md +26 -5
  112. package/templates/skills/orc-fast/SKILL.md +215 -187
  113. package/templates/skills/orc-grill/SKILL.md +233 -207
  114. package/templates/skills/orc-handoff/SKILL.md +223 -204
  115. package/templates/skills/orc-learn/SKILL.md +176 -156
  116. package/templates/skills/orc-mini/SKILL.md +41 -23
  117. package/templates/skills/orc-pact/SKILL.md +250 -218
  118. package/templates/skills/orc-pattern/SKILL.md +149 -124
  119. package/templates/skills/orc-poly/SKILL.md +237 -216
  120. package/templates/skills/orc-poly/references/gather.md +1 -1
  121. package/templates/skills/orc-pr-driver/SKILL.md +196 -167
  122. package/templates/skills/orc-pr-driver/references/orc-run-split.md +1 -1
  123. package/templates/skills/orc-pr-setup/SKILL.md +212 -184
  124. package/templates/skills/orc-quick/README.md +2 -2
  125. package/templates/skills/orc-quick/SKILL.md +346 -313
  126. package/templates/skills/orc-quick/references/dispatch-gate.md +12 -4
  127. package/templates/skills/orc-retro/SKILL.md +244 -222
  128. package/templates/skills/orc-retro/examples/retro-mock.md +171 -171
  129. package/templates/skills/orc-route/SKILL.md +183 -165
  130. package/templates/skills/orc-verify/SKILL.md +100 -86
  131. package/templates/skills/orc-wiki/SKILL.md +55 -206
  132. package/templates/skills/orc-wiki/references/phases/phase-0.md +71 -0
  133. package/templates/skills/orc-wiki/references/phases/phase-1.md +35 -0
  134. package/templates/skills/orc-wiki/references/phases/phase-2.md +52 -0
  135. package/templates/skills/orc-wiki/references/phases/phase-3.md +57 -0
  136. package/templates/skills/orc-wiki/references/phases/phase-3c.md +36 -0
  137. package/templates/agents/orc-advisor-fable-5.md +0 -50
  138. package/templates/agents/orc-analyst-fable-5.md +0 -115
  139. package/templates/agents/orc-judge-fable-5.md +0 -79
  140. package/templates/agents/orc-planner-fable-5.md +0 -152
  141. package/templates/agents/orc-reviewer-fable-5.md +0 -57
  142. package/templates/skills/_shared/fable5-override.md +0 -56
  143. package/templates/skills/orc-diy/references/blocks/execution.md +0 -42
  144. package/templates/skills/orc-diy/references/blocks/mock-example.md +0 -22
  145. package/templates/skills/orc-diy/references/blocks/planning.md +0 -34
  146. package/templates/skills/orc-diy/references/blocks/review.md +0 -18
  147. package/templates/skills/orc-diy/references/blocks/scoring.md +0 -16
  148. package/templates/skills/orc-diy/references/blocks/security.md +0 -25
  149. package/templates/skills/orc-diy/references/blocks/ship.md +0 -25
  150. package/templates/skills/orc-diy/references/blocks/summary.md +0 -18
  151. package/templates/skills/orc-diy/references/blocks/testgen.md +0 -17
  152. package/templates/skills/orc-diy/references/blocks/trace.md +0 -28
  153. package/templates/skills/orc-diy/references/blocks/verify.md +0 -25
package/templates/skills/orc-grill/SKILL.md CHANGED
@@ -1,207 +1,233 @@
1
- ---
2
- name: orc-grill
3
- description: >
4
- Standalone idea-sharpening lane — start from one vague sentence and leave with
5
- a settled idea written down. Use for "/orc-grill", "help me think this
6
- through", "I want X but I do not know what I want yet", "something is wrong
7
- with Y". It asks you rounds of questions (every question that is ready, in the
8
- same round), looks facts up itself instead of making you recite your own
9
- codebase, and stops only when YOU say the idea matches what you meant. Three
10
- exits: save it, carry it straight into /orc-analyze, or drop it. No scan, no
11
- plan, no build, no run folder, no code written. The orchestrator never answers
12
- its own questions.
13
- ---
14
-
15
- # ORC-GRILL
16
-
17
- The lane you use **before** you know what you want. One short sentence is a
18
- complete input:
19
-
20
- > "I want notifications for merchants."
21
- > "Something is wrong with our refunds."
22
-
23
- **Vagueness is the input here, not a reason to refuse.** Every other lane
24
- punishes a thin request — the planner refuses it, the analyst absorbs it into
25
- `ASSUMPTION` tags and then asks you the questions anyway, at scan prices. This
26
- lane asks them at conversation prices, and hands the result to those lanes
27
- already sharp.
28
-
29
- ## What this lane is NOT
30
-
31
- - **Not `/orc-analyze`.** Analyze checks a requirement **against the code**. It
32
- answers "does the repo really do that?". Grill answers "what do I actually
33
- want?". Grill first, analyze second — that order is the whole point.
34
- - **Not `/orc-plan` or `/orc`.** No tasks, no waves, no scoring, no build. It
35
- never writes code and never touches a file outside its own context doc.
36
- - **Not `/orc-learn`.** Learn teaches you an existing feature. Grill shapes one
37
- that does not exist yet.
38
- - **Not `/orc-quick`.** Quick DOES something now. Grill decides what should be
39
- done at all.
40
- - **Not `/orc-brainstorm`.** Brainstorm GENERATES options when you have none —
41
- it proposes and you judge. Grill sharpens the one you have — it asks and you
42
- answer. Brainstorm picks which mountain; grill picks the path up it.
43
-
44
- ## Nothing to configure
45
-
46
- Standalone and command-entry only. It reads `log_dir` and nothing else. No
47
- dispatch-forcing key applies, because it has no scored dispatch to force.
48
-
49
- ---
50
-
51
- ## G0 — Preflight (ONE time, silent, nothing here can stop the run)
52
-
53
- 1. **Config.** Read `log_dir`. Read no other key.
54
- 2. **Trace.** Write `log_dir/.current` = `run-grill-<slug>-<DDMMYY>-<HHMMSS>.txt`
55
- AND `touch the trace file` of that name in the SAME step. Both, or neither.
56
- The slug comes from the user's opening sentence; if it is too vague to slug,
57
- use `idea` plus the next free number.
58
- 3. **Knowledge probes.** Follow `../_shared/detecting-artifacts.md` — never a raw
59
- `find`, because `.claude` is hidden. `orc wiki status` · `orc pattern status
60
- <lang>` · `orc gotcha status`. **All three are helpful extras.** Missing
61
- knowledge never gates this lane, never triggers a scan, and never causes a
62
- fallback — it only means more of the frontier is a question instead of a
63
- lookup. Print ONE line each, then move on.
64
-
65
- ---
66
-
67
- ## G1 — The interview (the whole lane)
68
-
69
- **Follow `../_shared/interview.md` exactly.** It is the canonical mechanic and
70
- this lane does not get a private version of it. In short, and in that file's
71
- words:
72
-
73
- - Build a **design tree** of open questions from the opening sentence. Draw the
74
- dependencies — "which queue?" sits under "is this async at all?".
75
- - Ask the **whole frontier** each round: every open question whose prerequisites
76
- are settled, and nothing that depends on an answer you do not have yet.
77
- - Use the fixed shape, so a round can be answered by number:
78
- `❓ **Q1** — **<title>**: <body>`, then the recommendation alone on a `➡️` line.
79
- - **Facts are yours to find; decisions are the user's to make.** Resolve facts up
80
- the ladder — wiki status, wiki pages, cached pattern, `orc gotcha list`, and a
81
- read-only ad-hoc dispatch **last**. Never block a round on a running fact-find;
82
- only the questions genuinely downstream of it wait. And never soften the other
83
- half: **a lane that answers its own interview question has broken this
84
- contract.**
85
- - Tag every settled decision `intent` or `constraint` as it settles. The
86
- constraints are what later become `spec_invariants[]` — this is the step that
87
- makes the conversation load-bearing instead of merely pleasant.
88
-
89
- **Fact-finding dispatches.** Read-only recon is an **ad-hoc dispatch by model +
90
- effort** (the `/orc-quick` recon precedent), never a pinned agent — so no agent
91
- file ships for this lane and the hook writes no `SPAWN`/`RETURN` for it. Announce
92
- it on one line before it goes out (`recon: claude-sonnet-4-6 / medium — where
93
- refunds are written`) so the spend is never silent, but do NOT stop the round
94
- waiting for permission. Emit `DISPATCH … adhoc=true` and `VERIFY` yourself; the
95
- agent reports its own `actual_model` / `actual_effort`.
96
-
97
- **No question cap.** Some ideas settle in three questions and some need fifty. A
98
- cap would truncate exactly the case this lane exists for. The controls are the
99
- user's own words ("stop asking, just save it") and `/orc-explain` when a round
100
- gets dense.
101
-
102
- **"I do not even know what the options are" is a different lane, not a worse
103
- answer.** When a round comes back that way — the user cannot choose because
104
- nobody has generated anything to choose between — OFFER `/orc-brainstorm`, which
105
- proposes candidates on purpose and hands the chosen direction back here. Use
106
- `../_shared/lane-suspend.md` (`RETURN-TO`) so the trip returns to this same
107
- invocation. This does not soften the rule above: handing the user a lane whose job
108
- is generating options is not answering their question for them. It is an offer —
109
- "answer it roughly and I will keep going" stays on the menu.
110
-
111
- **Ungrillable questions get named, not talked around.** "How should this feel?"
112
- cannot be settled by talking — say so and point at ORC's `mock_example` phase
113
- (`mock-examples/<slug>/`). "Does the code really do that?" is `/orc-analyze`.
114
- Carrying an open question with the right instrument named is a finished answer.
115
-
116
- **The confirmation gate ends the lane, not an empty frontier.** Play the idea
117
- back in plain words and ask whether it matches what they meant. Only a yes ends
118
- it.
119
-
120
- ---
121
-
122
- ## G2 — Exit (ONE question, three answers)
123
-
124
- Ask once, after the confirmation gate:
125
-
126
- ```
127
- The idea is sharp now. What next?
128
-
129
- 1 Stop here — save it → writes orc-grill/<slug>/grill-context.md
130
- 2 Continue into /orc-analyze → checks it against the real code
131
- 3 Save the constraints to the pact → they outlive this run (/orc-pact)
132
- 4 Write it up as a document → /orc-doc, so other people can act on it
133
- 5 Stop, save nothing
134
- ```
135
-
136
- **Exit 3 (v0.46.0)** is present only when at least one decision settled here was
137
- tagged `constraint`. It writes the doc first, then hands those rows — quoted
138
- VERBATIM, with `origin: {lane: orc-grill, run: <this run>}` — to `/orc-pact`,
139
- which is the only thing that writes the ledger. Without it, every constraint this
140
- lane settles evaporates when the run ends, which is exactly the failure `/orc-pact`
141
- exists for. No constraints settled → the option is **absent with the reason
142
- printed**, never a dead number.
143
-
144
- **Exit 4 (v0.48.0)** writes the doc first, then enters `/orc-doc` with it as the
145
- D1 context. The interview has already produced exactly what D1 and D4 ask for, so
146
- those gates are **pre-answered from the artifact and the user only confirms** —
147
- which is the whole point of not re-asking a frozen question. Settled decisions
148
- travel with their `intent`/`constraint` tags, and any `spec_invariants[]` lands
149
- in `context.md`'s decision table. Exits 2 and 4 are different questions: 2 asks
150
- *is this buildable*, 4 asks *can somebody who was not here act on it*.
151
-
152
- **When is it sharp enough?** Exit 2 exists to clear the analyst's own entry
153
- floor, so use that floor as the bar:
154
- **analyzable ⇔ the input names (a) a subject the repo could plausibly contain —
155
- a feature, a flow, a file, or a document — AND (b) at least one thing that should
156
- be true when the work is done.** Below it, exit 2 just bounces straight back.
157
-
158
- **One extra exit, present ONLY when this run was entered with a `RETURN-TO`
159
- marker** (`../_shared/lane-suspend.md`): `Return to /<sender-lane> — carry these
160
- decisions back`, and it is the recommended option in that state. It is added to
161
- the menu, never a replacement: a user who picks "stop, save nothing" simply does
162
- not return, and the sender's snapshot is still on disk. Decisions travel back with
163
- their `intent`/`constraint` tags intact plus `source: /orc-grill`, and the
164
- **Facts looked up** rows go with them.
165
-
166
- - **1 — save.** Write the doc (below) and end the run.
167
- - **2 — hand off.** Write the doc first, then enter `/orc-analyze` with that file
168
- as the input. The analyst receives an already-scoped requirement and spends its
169
- tokens **grounding it in code** instead of re-asking scope. From there it is an
170
- ordinary analyze run — same phases, same gates, same `requirement-spec.md`.
171
- When this lane was entered FROM `/orc-analyze` (its reverse trigger), exit 2
172
- returns to that same invocation and the user retypes nothing.
173
- - **5 — drop it.** Write nothing. Still close the trace properly.
174
-
175
- ---
176
-
177
- ## The doc it writes
178
-
179
- ```
180
- <projectRoot>/orc-grill/<slug>/grill-context.md
181
- ```
182
-
183
- Project root, visible — **never inside `.claude/`**, never inside a run folder,
184
- for the same reason `/orc-quick` puts its doc there: a document a human reads and
185
- reuses belongs where the human can find it. One `.md` per slug, ever; the same
186
- slug re-opens and extends the same file. **Never staged for commit by ORC.**
187
-
188
- Shape, and what each part is for: `references/grill-doc.md`. The top carries a
189
- delimited `<!-- orc-grill:context -->` block so a later session reads the summary
190
- without reading the whole file.
191
-
192
- ## Behavior trace (always on — same as every lane)
193
-
194
- Follow `../orc/references/trace-protocol.md`. Lane name `grill`. This is a
195
- **single-dispatch** lane: **exactly ONE end-of-run packet**, dispatched solo to
196
- `orc-trace-writer-haiku-4-5` after the exit choice and BEFORE you delete
197
- `log_dir/.current`. It carries `run_meta`, the round-by-round event list, the
198
- settled decisions as `decisions` (the WHY layer), the exit taken, and `FINISH`. A
199
- run that ends with `zero new trace lines is a protocol violation`.
200
-
201
- ## Rules this lane always keeps
202
-
203
- Never answer your own question · never write code or edit a project file · never
204
- scan the repo · never force a lane on the user (exit 2 is an offer) · look facts
205
- up before asking for them · announce every dispatch · tag every decision `intent`
206
- or `constraint` · never stage `orc-grill/**` · tell the user to run `/usage`
207
- (never run it yourself).
1
+ ---
2
+ name: orc-grill
3
+ description: >
4
+ Standalone idea-sharpening lane — start from one vague sentence and leave with
5
+ a settled idea written down. Use for "/orc-grill", "help me think this
6
+ through", "I want X but I do not know what I want yet", "something is wrong
7
+ with Y". It asks you rounds of questions (every question that is ready, in the
8
+ same round), looks facts up itself instead of making you recite your own
9
+ codebase, and stops only when YOU say the idea matches what you meant. Three
10
+ exits: save it, carry it straight into /orc-analyze, or drop it. No scan, no
11
+ plan, no build, no run folder, no code written. The orchestrator never answers
12
+ its own questions.
13
+ ---
14
+
15
+ # ORC-GRILL
16
+
17
+ The lane you use **before** you know what you want. One short sentence is a
18
+ complete input:
19
+
20
+ > "I want notifications for merchants."
21
+ > "Something is wrong with our refunds."
22
+
23
+ **Vagueness is the input here, not a reason to refuse.** Every other lane
24
+ punishes a thin request — the planner refuses it, the analyst absorbs it into
25
+ `ASSUMPTION` tags and then asks you the questions anyway, at scan prices. This
26
+ lane asks them at conversation prices, and hands the result to those lanes
27
+ already sharp.
28
+
29
+ ## What this lane is NOT
30
+
31
+ - **Not `/orc-analyze`.** Analyze checks a requirement **against the code**. It
32
+ answers "does the repo really do that?". Grill answers "what do I actually
33
+ want?". Grill first, analyze second — that order is the whole point.
34
+ - **Not `/orc-plan` or `/orc`.** No tasks, no waves, no scoring, no build. It
35
+ never writes code and never touches a file outside its own context doc.
36
+ - **Not `/orc-learn`.** Learn teaches you an existing feature. Grill shapes one
37
+ that does not exist yet.
38
+ - **Not `/orc-quick`.** Quick DOES something now. Grill decides what should be
39
+ done at all.
40
+ - **Not `/orc-brainstorm`.** Brainstorm GENERATES options when you have none —
41
+ it proposes and you judge. Grill sharpens the one you have — it asks and you
42
+ answer. Brainstorm picks which mountain; grill picks the path up it.
43
+
44
+ ## Nothing to configure
45
+
46
+ Standalone and command-entry only. It reads `log_dir` and nothing else. No
47
+ dispatch-forcing key applies, because it has no scored dispatch to force.
48
+
49
+ ---
50
+
51
+ ## G0 — Preflight (ONE time, silent, nothing here can stop the run)
52
+
53
+ 1. **Config.** Read `log_dir`. Read no other key.
54
+ 2. **Trace.** Write `log_dir/.current` = `run-grill-<slug>-<DDMMYY>-<HHMMSS>.txt`
55
+ AND `touch the trace file` of that name in the SAME step. Both, or neither.
56
+ The slug comes from the user's opening sentence; if it is too vague to slug,
57
+ use `idea` plus the next free number.
58
+ 3. **Knowledge probes.** Follow `../_shared/detecting-artifacts.md` — never a raw
59
+ `find`, because `.claude` is hidden. `orc wiki status` · `orc pattern status
60
+ <lang>` · `orc gotcha status`. **All three are helpful extras.** Missing
61
+ knowledge never gates this lane, never triggers a scan, and never causes a
62
+ fallback — it only means more of the frontier is a question instead of a
63
+ lookup. Print ONE line each, then move on.
64
+
65
+ ---
66
+
67
+ The SHAPE of these steps — the order, and the four rules that make it worth
68
+ having — is `../_shared/phases/preflight.md` (`core`). The probes
69
+ themselves are this lane's own and stay here.
70
+
71
+ ## G1 — The interview (the whole lane)
72
+
73
+ **Follow `../_shared/interview.md` exactly.** It is the canonical mechanic and
74
+ this lane does not get a private version of it. In short, and in that file's
75
+ words:
76
+
77
+ - Build a **design tree** of open questions from the opening sentence. Draw the
78
+ dependencies — "which queue?" sits under "is this async at all?".
79
+ - Ask the **whole frontier** each round: every open question whose prerequisites
80
+ are settled, and nothing that depends on an answer you do not have yet.
81
+ - Use the fixed shape, so a round can be answered by number:
82
+ `❓ **Q1** — **<title>**: <body>`, then the recommendation alone on a `➡️` line.
83
+ - **Facts are yours to find; decisions are the user's to make.** Resolve facts up
84
+ the ladder — wiki status, wiki pages, cached pattern, `orc gotcha list`, and a
85
+ read-only ad-hoc dispatch **last**. Never block a round on a running fact-find;
86
+ only the questions genuinely downstream of it wait. And never soften the other
87
+ half: **a lane that answers its own interview question has broken this
88
+ contract.**
89
+ - Tag every settled decision `intent` or `constraint` as it settles. The
90
+ constraints are what later become `spec_invariants[]` — this is the step that
91
+ makes the conversation load-bearing instead of merely pleasant.
92
+
93
+ **Fact-finding dispatches.** Read-only recon is an **ad-hoc dispatch by model +
94
+ effort** (the `/orc-quick` recon precedent), never a pinned agent — so no agent
95
+ file ships for this lane and the hook writes no `SPAWN`/`RETURN` for it. Announce
96
+ it on one line before it goes out (`recon: claude-sonnet-4-6 / medium — where
97
+ refunds are written`) so the spend is never silent, but do NOT stop the round
98
+ waiting for permission. Emit `DISPATCH … adhoc=true` and `VERIFY` yourself; the
99
+ agent reports its own `actual_model` / `actual_effort`.
100
+
101
+ **No question cap.** Some ideas settle in three questions and some need fifty. A
102
+ cap would truncate exactly the case this lane exists for. The controls are the
103
+ user's own words ("stop asking, just save it") and `/orc-explain` when a round
104
+ gets dense.
105
+
106
+ **"I do not even know what the options are" is a different lane, not a worse
107
+ answer.** When a round comes back that way — the user cannot choose because
108
+ nobody has generated anything to choose between — OFFER `/orc-brainstorm`, which
109
+ proposes candidates on purpose and hands the chosen direction back here. Use
110
+ `../_shared/lane-suspend.md` (`RETURN-TO`) so the trip returns to this same
111
+ invocation. This does not soften the rule above: handing the user a lane whose job
112
+ is generating options is not answering their question for them. It is an offer —
113
+ "answer it roughly and I will keep going" stays on the menu.
114
+
115
+ **Ungrillable questions get named, not talked around.** "How should this feel?"
116
+ cannot be settled by talking — say so and point at ORC's `mock_example` phase
117
+ (`mock-examples/<slug>/`). "Does the code really do that?" is `/orc-analyze`.
118
+ Carrying an open question with the right instrument named is a finished answer.
119
+
120
+ **The confirmation gate ends the lane, not an empty frontier.** Play the idea
121
+ back in plain words and ask whether it matches what they meant. Only a yes ends
122
+ it.
123
+
124
+ ---
125
+
126
+ ## G2 — Exit (ONE question, three answers)
127
+
128
+ Ask once, after the confirmation gate:
129
+
130
+ ```
131
+ The idea is sharp now. What next?
132
+
133
+ 1 Stop here — save it → writes orc-grill/<slug>/grill-context.md
134
+ 2 Continue into /orc-analyze → checks it against the real code
135
+ 3 Save the constraints to the pact → they outlive this run (/orc-pact)
136
+ 4 Write it up as a document → /orc-doc, so other people can act on it
137
+ 5 Stop, save nothing
138
+ ```
139
+
140
+ **Exit 3 (v0.46.0)** is present only when at least one decision settled here was
141
+ tagged `constraint`. It writes the doc first, then hands those rows — quoted
142
+ VERBATIM, with `origin: {lane: orc-grill, run: <this run>}` — to `/orc-pact`,
143
+ which is the only thing that writes the ledger. Without it, every constraint this
144
+ lane settles evaporates when the run ends, which is exactly the failure `/orc-pact`
145
+ exists for. No constraints settled → the option is **absent with the reason
146
+ printed**, never a dead number.
147
+
148
+ **Exit 4 (v0.48.0)** writes the doc first, then enters `/orc-doc` with it as the
149
+ D1 context. The interview has already produced exactly what D1 and D4 ask for, so
150
+ those gates are **pre-answered from the artifact and the user only confirms** —
151
+ which is the whole point of not re-asking a frozen question. Settled decisions
152
+ travel with their `intent`/`constraint` tags, and any `spec_invariants[]` lands
153
+ in `context.md`'s decision table. Exits 2 and 4 are different questions: 2 asks
154
+ *is this buildable*, 4 asks *can somebody who was not here act on it*.
155
+
156
+ **When is it sharp enough?** Exit 2 exists to clear the analyst's own entry
157
+ floor, so use that floor as the bar:
158
+ **analyzable ⇔ the input names (a) a subject the repo could plausibly contain —
159
+ a feature, a flow, a file, or a document — AND (b) at least one thing that should
160
+ be true when the work is done.** Below it, exit 2 just bounces straight back.
161
+
162
+ **One extra exit, present ONLY when this run was entered with a `RETURN-TO`
163
+ marker** (`../_shared/lane-suspend.md`): `Return to /<sender-lane> — carry these
164
+ decisions back`, and it is the recommended option in that state. It is added to
165
+ the menu, never a replacement: a user who picks "stop, save nothing" simply does
166
+ not return, and the sender's snapshot is still on disk. Decisions travel back with
167
+ their `intent`/`constraint` tags intact plus `source: /orc-grill`, and the
168
+ **Facts looked up** rows go with them.
169
+
170
+ - **1 — save.** Write the doc (below) and end the run.
171
+ - **2 — hand off.** Write the doc first, then enter `/orc-analyze` with that file
172
+ as the input. The analyst receives an already-scoped requirement and spends its
173
+ tokens **grounding it in code** instead of re-asking scope. From there it is an
174
+ ordinary analyze run — same phases, same gates, same `requirement-spec.md`.
175
+ When this lane was entered FROM `/orc-analyze` (its reverse trigger), exit 2
176
+ returns to that same invocation and the user retypes nothing.
177
+ - **5 — drop it.** Write nothing. Still close the trace properly.
178
+
179
+ ---
180
+
181
+ ## The doc it writes
182
+
183
+ ```
184
+ <projectRoot>/orc-grill/<slug>/grill-context.md
185
+ ```
186
+
187
+ Project root, visible — **never inside `.claude/`**, never inside a run folder,
188
+ for the same reason `/orc-quick` puts its doc there: a document a human reads and
189
+ reuses belongs where the human can find it. One `.md` per slug, ever; the same
190
+ slug re-opens and extends the same file. **Never staged for commit by ORC.**
191
+
192
+ Shape, and what each part is for: `references/grill-doc.md`. The top carries a
193
+ delimited `<!-- orc-grill:context -->` block so a later session reads the summary
194
+ without reading the whole file.
195
+
196
+ ## Behavior trace (always on)
197
+
198
+ `../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
199
+ the file and the layers). Lane token `grill`, tier **Single-dispatch** —
200
+ exactly ONE end-of-run packet, dispatched solo before `.current` is deleted.
201
+ Nothing else about the protocol is restated here; a phase that ends with
202
+ `zero new trace lines is a protocol violation`.
203
+
204
+ Read-only recon is an **ad-hoc dispatch by model + effort**, never a pinned
205
+ agent — so the hook writes no `SPAWN`/`RETURN` for it. Emit `DISPATCH …
206
+ adhoc=true` and `VERIFY` yourself.
207
+
208
+ ## Rules this lane always keeps
209
+
210
+ Never answer your own question · never write code or edit a project file · never
211
+ scan the repo · never force a lane on the user (exit 2 is an offer) · look facts
212
+ up before asking for them · announce every dispatch · tag every decision `intent`
213
+ or `constraint` · never stage `orc-grill/**` · tell the user to run `/usage`
214
+ (never run it yourself).
215
+
216
+ ## Config
217
+
218
+ Resolve with `orc lane config orc-grill --json` and obey `effective`. Never merge
219
+ `.claude/orc.config.yaml` yourself, and never re-derive a precedence. Exit ≠ 0 →
220
+ say so and use `../_shared/config-precedence.md`'s documented defaults, out
221
+ loud. Nothing this lane reads is contested, gated or a stop, so it owes no
222
+ preflight line and has no gate to honour.
223
+
224
+ ## Calls
225
+
226
+ **ONE catalogue, and it is not you:** `orc lane calls orc-grill --json` names every
227
+ CLI call this lane makes, each with its exit-code contract, its cost, when to run
228
+ it, and what an EMPTY answer means. Never invent a spelling, never re-word an
229
+ exit code, and never re-derive a state word — the CLI's state words are the only
230
+ state words, and **an exit code is an ANSWER wherever that contract says so, not
231
+ a failure**. A call the answer does not name is a call this lane does not make.
232
+ Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
233
+ command you are about to run, out loud, before running it.