@azure-id/orc 1.9.1 → 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 (224) hide show
  1. package/CHANGELOG.md +390 -0
  2. package/README-id.md +20 -36
  3. package/README.md +24 -34
  4. package/bin/build-agents.js +206 -109
  5. package/bin/cli.js +760 -62
  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/onboarding-content.js +4 -4
  13. package/bin/pricing.json +207 -200
  14. package/bin/run-undo.js +398 -0
  15. package/bin/trace-write.js +657 -0
  16. package/bin/verify-contracts.js +527 -81
  17. package/bin/verify-package.js +58 -11
  18. package/bin/webui/api.js +26 -0
  19. package/bin/webui/app.html +239 -232
  20. package/bin/webui/css/00-tokens.css +110 -92
  21. package/bin/webui/css/04-motion.css +249 -152
  22. package/bin/webui/css/06-responsive.css +203 -178
  23. package/bin/webui/css/panels/behaviour.css +205 -0
  24. package/bin/webui/css/panels/knowledge.css +563 -116
  25. package/bin/webui/fixtures/behaviour.js +532 -0
  26. package/bin/webui/fixtures/extra.js +2036 -2036
  27. package/bin/webui/fixtures/hookui.js +5 -5
  28. package/bin/webui/fixtures/index.js +34 -0
  29. package/bin/webui/fixtures/knowledge.js +7 -1
  30. package/bin/webui/fixtures/settings.js +305 -305
  31. package/bin/webui/fixtures/stats.js +16 -0
  32. package/bin/webui/i18n/en/behaviour.json +143 -0
  33. package/bin/webui/i18n/en/knowledge.json +117 -2
  34. package/bin/webui/i18n/en/nav.json +25 -24
  35. package/bin/webui/i18n/en/tour.json +37 -35
  36. package/bin/webui/i18n/id/behaviour.json +143 -0
  37. package/bin/webui/i18n/id/knowledge.json +117 -2
  38. package/bin/webui/i18n/id/nav.json +25 -24
  39. package/bin/webui/i18n/id/tour.json +37 -35
  40. package/bin/webui/js/01-i18n.js +155 -154
  41. package/bin/webui/js/90-tour.js +498 -494
  42. package/bin/webui/js/91-shortcuts.js +126 -126
  43. package/bin/webui/js/99-boot.js +121 -118
  44. package/bin/webui/js/panels/behaviour.js +1022 -0
  45. package/bin/webui/js/panels/knowledge.js +552 -7
  46. package/bin/webui/js/panels/overview.js +13 -4
  47. package/mock-run/INDEX.md +109 -107
  48. package/mock-run/context-combiner.md +100 -100
  49. package/mock-run/gotcha-import.md +118 -0
  50. package/mock-run/habits.md +129 -0
  51. package/mock-run/orc-budget.md +534 -534
  52. package/mock-run/orc-challenge-council.md +262 -262
  53. package/mock-run/orc-quick.md +6 -1
  54. package/mock-run/orc-ultra.md +103 -103
  55. package/package.json +1 -1
  56. package/templates/agents/MODEL-MAPPING.md +49 -49
  57. package/templates/agents/orc-advisor-opus-5-xhigh.md +50 -56
  58. package/templates/agents/orc-analyze-mini-opus-5-med.md +55 -60
  59. package/templates/agents/orc-analyze-mini-sonnet-5-high.md +55 -58
  60. package/templates/agents/orc-challenge-advisor-opus-5-med.md +75 -75
  61. package/templates/agents/orc-challenge-contrarian-opus-5-high.md +110 -110
  62. package/templates/agents/orc-challenge-executor-opus-5-med.md +114 -114
  63. package/templates/agents/orc-challenge-expansionist-opus-5-med.md +112 -112
  64. package/templates/agents/orc-challenge-judge-opus-5-high.md +132 -132
  65. package/templates/agents/orc-challenge-outsider-opus-5-low.md +109 -109
  66. package/templates/agents/orc-challenge-principles-opus-5-high.md +109 -109
  67. package/templates/agents/orc-challenge-reader-opus-5-low.md +90 -90
  68. package/templates/agents/orc-claude-writer-opus-4-8-high.md +48 -53
  69. package/templates/agents/orc-claude-writer-opus-5-med.md +48 -55
  70. package/templates/agents/orc-context-combiner-opus-5-high.md +78 -88
  71. package/templates/agents/orc-doc-checker-opus-5-low.md +108 -108
  72. package/templates/agents/orc-doc-writer-opus-5-med.md +134 -134
  73. package/templates/agents/orc-executor-haiku-4-5.md +14 -6
  74. package/templates/agents/orc-executor-opus-4-7-high.md +14 -6
  75. package/templates/agents/orc-executor-opus-4-7-med.md +14 -6
  76. package/templates/agents/orc-executor-opus-4-8-high.md +14 -6
  77. package/templates/agents/orc-executor-opus-5-high.md +15 -7
  78. package/templates/agents/orc-executor-opus-5-low.md +15 -7
  79. package/templates/agents/orc-executor-opus-5-med.md +15 -7
  80. package/templates/agents/orc-executor-sonnet-4-6-high.md +14 -6
  81. package/templates/agents/orc-executor-sonnet-4-6-med.md +14 -6
  82. package/templates/agents/orc-executor-sonnet-5-high.md +14 -6
  83. package/templates/agents/orc-graph-noter-sonnet-4-6-med.md +1 -10
  84. package/templates/agents/orc-judge-opus-5-xhigh.md +81 -85
  85. package/templates/agents/orc-learn-writer-opus-5-low.md +67 -73
  86. package/templates/agents/orc-pattern-codifier-opus-5-med.md +58 -65
  87. package/templates/agents/orc-pattern-codifier-sonnet-5-high.md +58 -63
  88. package/templates/agents/orc-planner-mini-opus-5-med.md +4 -7
  89. package/templates/agents/orc-planner-mini-sonnet-5-high.md +2 -3
  90. package/templates/agents/orc-planner-opus-5-med.md +157 -160
  91. package/templates/agents/orc-recon-opus-5-low.md +3 -10
  92. package/templates/agents/orc-recon-sonnet-4-6-med.md +1 -8
  93. package/templates/agents/orc-retro-opus-5-med.md +8 -10
  94. package/templates/agents/orc-retro-sonnet-5-high.md +6 -7
  95. package/templates/agents/orc-reviewer-opus-5-med.md +96 -60
  96. package/templates/agents/orc-scout-opus-5-low.md +35 -40
  97. package/templates/agents/orc-scout-sonnet-4-6-high.md +35 -39
  98. package/templates/agents/orc-system-analyst-opus-5-high.md +115 -120
  99. package/templates/agents/orc-test-author-opus-5-med.md +70 -71
  100. package/templates/agents/orc-test-designer-opus-5-high.md +158 -158
  101. package/templates/agents/orc-test-interpreter-opus-5-low.md +130 -130
  102. package/templates/agents/orc-trace-writer-haiku-4-5.md +3 -7
  103. package/templates/agents/orc-verifier-opus-5-med.md +77 -69
  104. package/templates/agents/orc-wiki-scanner-opus-4-8-high.md +74 -79
  105. package/templates/agents/orc-wiki-scanner-opus-5-med.md +74 -81
  106. package/templates/agents/orc-wiki-scanner-sonnet-5-high.md +97 -106
  107. package/templates/commands/orc-analyze.md +13 -21
  108. package/templates/commands/orc-fast.md +10 -15
  109. package/templates/commands/orc-poly.md +12 -21
  110. package/templates/commands/orc-pr-driver.md +11 -30
  111. package/templates/commands/orc-pr-setup.md +10 -31
  112. package/templates/commands/orc-route.md +11 -41
  113. package/templates/commands/orc-test.md +5 -60
  114. package/templates/commands/orc-ultra.md +17 -17
  115. package/templates/commands/orc-verify.md +11 -11
  116. package/templates/hooks/README.md +36 -2
  117. package/templates/hooks/orc-effort-guard.js +178 -178
  118. package/templates/hooks/orc-session-hook.js +264 -0
  119. package/templates/hooks/orc-statusline.js +9 -7
  120. package/templates/skills/_shared/README.md +9 -0
  121. package/templates/skills/_shared/code-graph.md +48 -56
  122. package/templates/skills/_shared/config-precedence.md +200 -198
  123. package/templates/skills/_shared/extra-dispatch.md +1331 -1346
  124. package/templates/skills/_shared/gotchas.md +228 -177
  125. package/templates/skills/_shared/habits.md +101 -0
  126. package/templates/skills/_shared/lane-contract.md +84 -0
  127. package/templates/skills/_shared/opus5-only.md +8 -8
  128. package/templates/skills/_shared/phases/README.md +142 -83
  129. package/templates/skills/_shared/phases/analyst-gates.md +125 -136
  130. package/templates/skills/_shared/phases/execution.md +8 -14
  131. package/templates/skills/_shared/phases/house-rules.md +27 -32
  132. package/templates/skills/_shared/phases/intake.md +127 -133
  133. package/templates/skills/_shared/phases/mock-example.md +46 -56
  134. package/templates/skills/_shared/phases/plan-handoff.md +91 -97
  135. package/templates/skills/_shared/phases/planning.md +7 -17
  136. package/templates/skills/_shared/phases/preflight.md +19 -42
  137. package/templates/skills/_shared/phases/review.md +23 -27
  138. package/templates/skills/_shared/phases/rules.md +18 -42
  139. package/templates/skills/_shared/phases/scoring.md +55 -65
  140. package/templates/skills/_shared/phases/security-checklist.md +46 -50
  141. package/templates/skills/_shared/phases/security.md +45 -55
  142. package/templates/skills/_shared/phases/ship.md +6 -15
  143. package/templates/skills/_shared/phases/stop-resume.md +2 -5
  144. package/templates/skills/_shared/phases/summary.md +73 -48
  145. package/templates/skills/_shared/phases/testgen.md +41 -51
  146. package/templates/skills/_shared/phases/trace-verbs.md +433 -0
  147. package/templates/skills/_shared/phases/trace.md +136 -367
  148. package/templates/skills/_shared/phases/verify.md +62 -70
  149. package/templates/skills/_shared/phases/wave-grouping.md +128 -133
  150. package/templates/skills/_shared/phases/wiki-consult.md +10 -6
  151. package/templates/skills/_shared/read-ladder.md +2 -55
  152. package/templates/skills/_shared/return-validation.md +17 -70
  153. package/templates/skills/_shared/review-slice.md +79 -0
  154. package/templates/skills/_shared/smoke-gate.md +46 -28
  155. package/templates/skills/context-combiner/SKILL.md +16 -45
  156. package/templates/skills/context-combiner/schemas/combined-report.md +78 -78
  157. package/templates/skills/orc/README.md +2 -2
  158. package/templates/skills/orc/SKILL.md +41 -69
  159. package/templates/skills/orc/config.md +9 -9
  160. package/templates/skills/orc/examples/full-run-mock.md +73 -73
  161. package/templates/skills/orc/references/effort-and-mode.md +222 -222
  162. package/templates/skills/orc/references/pattern-gate.md +89 -89
  163. package/templates/skills/orc/references/phases/intake.md +41 -47
  164. package/templates/skills/orc/references/phases/integration.md +13 -19
  165. package/templates/skills/orc/references/preflight-report.md +10 -11
  166. package/templates/skills/orc/references/ultra-mode.md +11 -9
  167. package/templates/skills/orc/subskills/orc-execution/SKILL.md +27 -73
  168. package/templates/skills/orc/subskills/orc-execution/core.md +12 -99
  169. package/templates/skills/orc/subskills/orc-execution/subagent.md +14 -13
  170. package/templates/skills/orc/subskills/orc-planner/SKILL.md +2 -2
  171. package/templates/skills/orc/subskills/orc-planner-mini/SKILL.md +121 -121
  172. package/templates/skills/orc/subskills/orc-review-verify/SKILL.md +35 -76
  173. package/templates/skills/orc/subskills/orc-review-verify/core.md +52 -135
  174. package/templates/skills/orc/subskills/orc-review-verify/subagent.md +7 -7
  175. package/templates/skills/orc/subskills/orc-testgen/SKILL.md +34 -45
  176. package/templates/skills/orc/subskills/orc-testgen/core.md +20 -59
  177. package/templates/skills/orc/subskills/orc-testgen/subagent.md +7 -7
  178. package/templates/skills/orc-advisor/SKILL.md +56 -60
  179. package/templates/skills/orc-analyze/SKILL.md +32 -68
  180. package/templates/skills/orc-analyze/examples/analyze-mock.md +42 -42
  181. package/templates/skills/orc-analyze/schemas/report-audit.md +84 -83
  182. package/templates/skills/orc-analyze/schemas/report-prose.md +64 -63
  183. package/templates/skills/orc-analyze/schemas/report-requirement.md +78 -78
  184. package/templates/skills/orc-analyze-mini/SKILL.md +35 -70
  185. package/templates/skills/orc-challenge/README.md +142 -142
  186. package/templates/skills/orc-challenge/examples/council-full-roster.md +273 -273
  187. package/templates/skills/orc-challenge/references/council.md +315 -315
  188. package/templates/skills/orc-challenge/references/intake.md +171 -171
  189. package/templates/skills/orc-claude/SKILL.md +14 -14
  190. package/templates/skills/orc-diy/README.md +174 -143
  191. package/templates/skills/orc-diy/SKILL.md +23 -74
  192. package/templates/skills/orc-diy/references/blocks/pattern.md +18 -18
  193. package/templates/skills/orc-diy/references/flow-schema.md +1 -1
  194. package/templates/skills/orc-doc/README.md +229 -229
  195. package/templates/skills/orc-doc/examples/orc-doc-prd-run.md +325 -325
  196. package/templates/skills/orc-doc/references/chunking.md +527 -527
  197. package/templates/skills/orc-fast/SKILL.md +45 -73
  198. package/templates/skills/orc-judge/SKILL.md +77 -82
  199. package/templates/skills/orc-learn/SKILL.md +14 -14
  200. package/templates/skills/orc-learn/examples/learn-run-mock.md +61 -61
  201. package/templates/skills/orc-mini/SKILL.md +65 -113
  202. package/templates/skills/orc-pattern/SKILL.md +27 -48
  203. package/templates/skills/orc-poly/SKILL.md +32 -61
  204. package/templates/skills/orc-pr-driver/SKILL.md +25 -51
  205. package/templates/skills/orc-pr-driver/references/green-gate.md +113 -105
  206. package/templates/skills/orc-pr-setup/SKILL.md +20 -45
  207. package/templates/skills/orc-quick/README.md +43 -2
  208. package/templates/skills/orc-quick/SKILL.md +76 -107
  209. package/templates/skills/orc-quick/references/dispatch-gate.md +16 -5
  210. package/templates/skills/orc-quick/references/gh-mode.md +48 -1
  211. package/templates/skills/orc-quick/references/look.md +3 -1
  212. package/templates/skills/orc-retro/SKILL.md +19 -18
  213. package/templates/skills/orc-retro/examples/retro-mock.md +1 -1
  214. package/templates/skills/orc-route/SKILL.md +25 -45
  215. package/templates/skills/orc-test/SKILL.md +16 -37
  216. package/templates/skills/orc-verify/SKILL.md +21 -39
  217. package/templates/skills/orc-verify/examples/verify-mock.md +33 -33
  218. package/templates/skills/orc-wait/SKILL.md +156 -163
  219. package/templates/skills/orc-wiki/references/extra.md +1 -1
  220. package/templates/skills/orc-wiki/references/phases/phase-0.md +1 -6
  221. package/templates/skills/orc-wiki/references/phases/phase-1.md +1 -6
  222. package/templates/skills/orc-wiki/references/phases/phase-2.md +1 -6
  223. package/templates/skills/orc-wiki/references/phases/phase-3.md +1 -6
  224. package/templates/skills/orc-wiki/references/phases/phase-3c.md +1 -6
@@ -3,17 +3,15 @@ name: orc
3
3
  description: >
4
4
  Use when orchestrating a multi-task build through a full pipeline: intake →
5
5
  planning → scored parallel execution → review → verify → ship. Triggers:
6
- "orchestrate this", "build this in parallel", "run this with subagents",
7
- "use orc", or any request to take a feature/spec from intent to PR with
8
- subagents. Routes planning to Superpowers, OpenSpec, or its own planner;
9
- schedules conflict-free waves; scores each task to pick the cheapest capable
10
- model; checkpoints eagerly; survives compaction and fresh-session resume.
11
- Stack-agnostic.
6
+ "orchestrate this", "build this in parallel", "run this with subagents", "use
7
+ orc", or any request to take a feature/spec from intent to PR with subagents.
8
+ Scores each task to pick the cheapest capable model, and survives compaction
9
+ and fresh-session resume. Stack-agnostic.
12
10
  ---
13
11
 
14
12
  # ORC (orchestrator spine)
15
13
 
16
- You are the **orchestrator**: **Opus 4.8 high — or Opus 5 / Fable 5 at medium+**
14
+ You are the **orchestrator**: **Opus 4.8 high — or Opus 5.5 / Fable 5 at medium+**
17
15
  (never downgrade yourself). You own the schemas, the dependency/conflict graph, wave
18
16
  scheduling, per-task model scoring, all checkpoint writes, user Q&A relay, and
19
17
  every decision below. Workers stay dumb and isolated.
@@ -24,8 +22,8 @@ version of a reference you haven't loaded this run. Detect the stack from the re
24
22
 
25
23
  ## Preflight gate (before Phase 0 — do this FIRST)
26
24
 
27
- Confirm you are **Opus 4.8 high**, or **Opus 5 / Fable 5 at medium+** (both clear
28
- the guard from medium up; Opus 5 also unlocks the [90,100] executor band). Effort
25
+ Confirm you are **Opus 4.8 high**, or **Opus 5.5 / Fable 5 at medium+** (both clear
26
+ the guard from medium up; Opus 5.5 also unlocks the [90,100] executor band). Effort
29
27
  is hard-blocked by the `orc-effort-guard.js` PreToolUse hook; the model cannot be
30
28
  (hooks can't see it) — the statusline warns. On a weaker tier **STOP immediately**
31
29
  and tell the user to switch the main session and re-run — never intake below it
@@ -69,11 +67,11 @@ themselves are this lane's own and stay here.
69
67
 
70
68
  ## Dispatched roles (you never do this work yourself)
71
69
 
72
- **Analyst** `orc-analyze` (Opus 5 high): doc OR bare request →
70
+ **Analyst** `orc-analyze` (Opus 5.5 high): doc OR bare request →
73
71
  scope-bounded, code-grounded report + spec; standard or opt-in DEEP (scouts).
74
- **Context-combiner** (Opus 5 high): merges 2+ related confirmed analyses
72
+ **Context-combiner** (Opus 5.5 high): merges 2+ related confirmed analyses
75
73
  into ONE combined spec; build only on `handoff_ready` with `coverage_pct` =
76
- 100; full lane only. **Planner** `subskills/orc-planner` (Opus 5 medium):
74
+ 100; full lane only. **Planner** `subskills/orc-planner` (Opus 5.5 medium):
77
75
  request or spec → planning-output. Scout dispatch, analyst-return gates,
78
76
  combiner tracking, the `git_head` staleness valve, and the Phase 1 exit gate
79
77
  are YOURS and deterministic — load `../_shared/phases/analyst-gates.md` at their
@@ -81,7 +79,7 @@ trigger points; emit `GATE` trace lines.
81
79
 
82
80
  ## Dispatch via named agents (not prose)
83
81
 
84
- **`orc run inflight` before ANY re-dispatch** (0 clear · 1 in-flight · 2 unknown).
82
+ **`orc run inflight` before ANY re-dispatch.**
85
83
  A Task error does not kill the agent behind it, and exit 2 REFUSES by default —
86
84
  `a lane that re-dispatches over a live attempt` has broken the contract. Canonical: `_shared/return-validation.md` §0.
87
85
 
@@ -96,63 +94,39 @@ requeue) run the same formula, inherit the original task's risk floor, and never
96
94
  dispatch below the finding-task's band. Fixed roles dispatch BY NAME (analyst /
97
95
  combiner / planner / reviewer / verifier — see `config.md`'s fixed-role table +
98
96
  `.claude/agents/MODEL-MAPPING.md`). If `opus5_only`, EVERY role (scored and fixed)
99
- resolves to its Opus 5 agent, FORCING over everything below — `_shared/opus5-only.md`.
97
+ resolves to its Opus 5.5 agent, FORCING over everything below — `_shared/opus5-only.md`.
100
98
  Caveat: a subagent's model can't exceed the MAIN session's tier — run the main
101
99
  session on Opus or the Opus pins silently fall back (the original "wrong model" bug).
102
100
 
103
- ## Config (read at run start)
104
-
105
- **ONE resolver, and it is not you:** `orc lane config orc --json`. Obey
106
- `effective`, print every line in `announce[]` VERBATIM at preflight, and honour
107
- `stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
108
- from `.claude/orc.config.yaml` — a key this lane does not read is not in the
109
- answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
110
- the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
111
- documented defaults, out loud. Priorities and families:
112
- `../_shared/config-precedence.md`.
113
-
114
- ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
115
-
116
- `orc rules slice --lane orc --json` is the ONLY assembler; never build
117
- the card here. It rides under the house rules and above the task —
118
- **house rules > your project's rules > ORC's own packs** — and its `line` prints
119
- VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
120
- never a silent choice) and `rules_overridden[]`.
121
- ## Calls
122
-
123
- **ONE catalogue, and it is not you:** `orc lane calls orc --json` names every
124
- CLI call this lane makes, each with its exit-code contract, its cost, when to run
125
- it, and what an EMPTY answer means. Never invent a spelling, never re-word an
126
- exit code, and never re-derive a state word — the CLI's state words are the only
127
- state words, and **an exit code is an ANSWER wherever that contract says so, not
128
- a failure**. A call the answer does not name is a call this lane does not make.
129
- Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
130
- command you are about to run, out loud, before running it.
101
+ ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
102
+
103
+ - **Calls:** `orc lane calls orc --json` names every call and its exit codes.
104
+ **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
105
+ - **Config:** `orc lane config orc --json`. Obey `effective`, print every line
106
+ in `announce[]` VERBATIM at preflight, and honour `stops[]` before wave 1.
107
+ Never merge `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).
108
+ - **Rules:** `orc rules slice --lane orc --json` is the ONLY assembler
109
+ (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
131
110
 
132
111
  ## Behavior trace (PERMANENT — always on, no config toggle)
133
112
 
134
- Follow `../_shared/phases/trace.md` (ALWAYS load it at run start). The
135
- `orc-trace.js` hook writes the `SPAWN`/`RETURN`/`PHASE-EDGE` skeleton
136
- deterministically; the rich narrative is **dispatched, never remembered** — every
137
- `emit <VERB>` step below means RECORD that event, with its REAL timestamp, into
138
- the current **phase packet**; you never append a trace line yourself. Run start:
139
- create `log_dir`, write `log_dir/.current` = `run-orc-<slug>-<DDMMYY>-<HHMMSS>.txt`
140
- AND `touch the trace file` of that name in the SAME step; store `trace_path`.
113
+ Follow `../_shared/phases/trace.md` (ALWAYS load it at run start; pairing rule,
114
+ packet shape and run end are there). Lane token `orc`, tier **Build lanes**. The
115
+ `orc-trace.js` hook writes the `SPAWN`/`RETURN`/`PHASE-EDGE` skeleton; the
116
+ narrative is **dispatched, never remembered** — every `emit <VERB>` step below
117
+ means RECORD that event, with its REAL timestamp, into the current **phase packet**. Run start: create `log_dir`, write `log_dir/.current`
118
+ = `run-orc-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
119
+ in the SAME step; store `trace_path`.
141
120
  **Under `ultra_mode` the lane segment is `ultra`, not `orc`** (`run-ultra-<slug>-…`)
142
121
  — the filename IS the per-lane data, so an ultra run named `orc` is counted as a
143
122
  plain `/orc` run forever, hiding the costliest lane in every usage report.
144
- **Phase close = dispatch `orc-trace-writer-haiku-4-5`** with that packet
145
- (`phase`, `events[]`, and `decisions` — the WHY: scoring rationale, the user's
146
- answers VERBATIM, what you rejected; `run_meta` on the FIRST packet only).
147
- **Pairing rule:** issue phase N's writer dispatch in the SAME tool block as phase
148
- N+1's first dispatch (a phase with no next dispatch sends it solo, before its
149
- user-facing output); the first packet is solo + synchronous — it repairs a
150
- hook-bootstrapped filename. `DISPATCH`/`VERIFY` models are derived from the agent
151
- NAME and checked against each return's `actual_model`/`actual_effort` — surface
152
- any ⛔ DOWNGRADE to the user, not just into the packet. A phase ending with
153
- `zero new trace lines is a protocol violation` — build and dispatch its packet
154
- NOW, with the events' real stamps. Run end (Phase 8 or abort): the `FINISH`
155
- packet goes out and RETURNS, then delete `log_dir/.current`.
123
+ **Phase close = `orc trace write --packet -`** (exit ≠ 0 → `orc-trace-writer-haiku-4-5`).
124
+ The first packet is solo — it repairs a hook-bootstrap filename.
125
+ `DISPATCH`/`VERIFY` models are derived from the agent NAME and checked against
126
+ each return's `actual_model`/`actual_effort` — surface any ⛔ DOWNGRADE to the
127
+ user, not just into the packet. A phase ending with
128
+ `zero new trace lines is a protocol violation` — build and write its packet
129
+ NOW, with the events' real stamps.
156
130
 
157
131
  ## Extra — a band that executes OFF Claude (config `extra_enabled`, default false)
158
132
 
@@ -175,7 +149,7 @@ review/verify re-check the invariants + `validation_gate[]` lines. Load
175
149
  ## Ultra lane (`/orc-ultra`)
176
150
 
177
151
  `/orc-ultra` sets `ultra_mode: true` RUN-SCOPED (never persisted): full pipeline
178
- + Opus 4.8 max Advisor (Phase U0) + three judge gates + forced overrides (deep
152
+ + Opus 5.5 xhigh Advisor (Phase U0) + three judge gates + forced overrides (deep
179
153
  analyze, pattern/testgen/security on, executor tier floor); never on plain
180
154
  `/orc` or orc-mini. Load `references/ultra-mode.md` at Phase 0 when ultra_mode;
181
155
  orc-advisor / orc-judge load at their dispatch points.
@@ -214,10 +188,9 @@ them; they are never dispatched as subagents).
214
188
 
215
189
  ## Phases
216
190
 
217
- `orc lane phases orc --json` **is** the pipeline — the CLI owns the list and
218
- its order, and this table is the human index of it. Never derive the order
219
- from these filenames; a second idea of the pipeline is the drift the manifest
220
- exists to prevent.
191
+ `orc lane phases orc --json` **is** the pipeline; this table is only its human
192
+ index. **The CLI owns the order**: never derive it from these filenames
193
+ (`../_shared/lane-contract.md` §Phases).
221
194
 
222
195
  **Read a row when its phase fires, not on activation.** Every row is
223
196
  `on-phase` — this spine deliberately carries no `always` phase pointer. **Read
@@ -228,8 +201,7 @@ each row.
228
201
 
229
202
  W13 gave those ten a second reader (`orc-diy`), so they moved to
230
203
  `_shared/phases/`. Intake and Integration have one consumer each and stay home
231
- — a file with one consumer stays home. W14 (`orc-mini`/`orc-fast`) is what adds
232
- a `trim` layer beside the `full` one.
204
+ — a file with one consumer stays home.
233
205
 
234
206
  | # | Phase | File | Read | Trace |
235
207
  |---|-------|------|------|-------|
@@ -252,4 +224,4 @@ their config key is resolved by `orc lane config orc --json`, never read raw.
252
224
  ## Waiting mid-run (`/orc-wait`)
253
225
 
254
226
  Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
255
- Checkpoint **full** · safe point **wave or phase edge**. `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 between a dispatch and its validated return, or before the smoke gate has reported.
227
+ Checkpoint **full** · safe point **wave or phase edge**.
@@ -35,13 +35,13 @@ canonical 6-band table, and dispatches the matching **executor agent**.
35
35
  | [30,40) | claude-sonnet-4-6 | medium | orc-executor-sonnet-4-6-med |
36
36
  | [40,55) | claude-sonnet-4-6 | high | orc-executor-sonnet-4-6-high |
37
37
  | [55,65) | claude-sonnet-5 | high | orc-executor-sonnet-5-high |
38
- | [65,90) | claude-opus-5 | low | orc-executor-opus-5-low |
39
- | [90,100] | claude-opus-5 | medium | orc-executor-opus-5-med |
38
+ | [65,90) | claude-opus-5-5 | low | orc-executor-opus-5-low |
39
+ | [90,100] | claude-opus-5-5 | medium | orc-executor-opus-5-med |
40
40
 
41
41
  (Haiku has no effort ladder — that agent carries no `effort:` field.) The risk
42
42
  floor (≥70) lands `orc-executor-opus-5-low` at minimum in THIS table. Above ~65
43
43
  the useful dial stopped being the model GENERATION and became the EFFORT, which
44
- is why the old four Opus rows are two. **Every band from 65 needs an Opus 5 MAIN
44
+ is why the old four Opus rows are two. **Every band from 65 needs an Opus 5.5 MAIN
45
45
  session** or it silently falls back to the session model (the tier-honesty rule
46
46
  reports the downgrade) — two bands where it used to be one, and that is the cost
47
47
  of this table.
@@ -59,15 +59,15 @@ One model, EFFORT as the cost dial. Off by default; nothing changes until set.
59
59
 
60
60
  | Score | Model | Effort | Executor agent |
61
61
  |-------|-------|--------|----------------|
62
- | [0,90) | claude-opus-5 | low | orc-executor-opus-5-low |
63
- | [90,100] | claude-opus-5 | medium | orc-executor-opus-5-med |
62
+ | [0,90) | claude-opus-5-5 | low | orc-executor-opus-5-low |
63
+ | [90,100] | claude-opus-5-5 | medium | orc-executor-opus-5-med |
64
64
 
65
65
  Two bands, sharing the 90 edge with the default table's top two rows. That
66
- symmetry is the point: once the default table's high end is already Opus 5 with
66
+ symmetry is the point: once the default table's high end is already Opus 5.5 with
67
67
  effort as the dial, this mode differs from it only BELOW 65, so a third band
68
68
  would be a distinction the default table stopped making.
69
69
 
70
- **Tier cost:** today TWO bands in six need an Opus 5 main session; with this on,
70
+ **Tier cost:** today TWO bands in six need an Opus 5.5 main session; with this on,
71
71
  EVERY dispatch does, so a lower session downgrades every task (warn-only — a
72
72
  hook can gate effort, never model). **Scope:** it is NOT executor-only — it also
73
73
  forces every fixed role below, across every lane. orc-diy's table
@@ -93,8 +93,8 @@ un-shown number.
93
93
  | Ultra advisor (/orc-ultra only) | orc-advisor-opus-5-xhigh |
94
94
  | Ultra judge (/orc-ultra only) | orc-judge-opus-5-xhigh |
95
95
 
96
- Under `opus5_only`, every role above that is not already `claude-opus-5`
97
- dispatches its Opus 5 variant instead — plus the roles owned by other lanes
96
+ Under `opus5_only`, every role above that is not already `claude-opus-5-5`
97
+ dispatches its Opus 5.5 variant instead — plus the roles owned by other lanes
98
98
  (scout, wiki scanner, CLAUDE.md writer, retro miner, fast executor).
99
99
 
100
100
  ## Where each subsystem's rule is written down
@@ -1,73 +1,73 @@
1
- # Example — Annotated Full Run (v2.2, dry run)
2
-
3
- O: = orchestrator (Opus 4.8 high, always) · U: = user. Nothing real. The
4
- orchestrator NEVER implements — it always spawns scored subagents.
5
-
6
- U: Orchestrate: merchant notification system — in-app, email digest, prefs page.
7
-
8
- ## Phase 0 — Intake
9
- O: Creates run folder run/merchant-notifications/ FIRST.
10
- [reads repo: TS/yarn/jest — asks nothing about stack] Rough size: medium+ → 4-question tier (one batched round):
11
- 1) What should exist when done? 2) Out of scope? 3) How do we know it's done? 4) Patterns/files to avoid?
12
- U: [answers] no push, no admin; bell count + both digest schedules + prefs persist; follow services/ pattern, don't touch auth_service.
13
- O: [drafts run/merchant-notifications/intent-spec.md] Sign-off: gate or soft? (default gate)
14
- U: gate → approved
15
-
16
- ## Phase 1 — Planning
17
- O: Planner? U: OpenSpec
18
- O: [6 tasks with declared_files incl. tests + per-file grounding attestations + sliced acceptance[], depends_on, spec_ref] ⚠ T1/T2 share models/notification.ts → scheduling separates them.
19
- Grounding spot-check (Phase 1 exit): globs all `exists` paths — 13/14 present, models/notifcation.ts MISSING (typo) → plan bounced to planner with the miss list → corrected to models/notification.ts ✓.
20
-
21
- ## Phase 2 — Effort, dispatch style, scoring
22
- O: Refined: medium, partially dependent. Recommend PARALLEL waves. Confirm? U: yes. Batch pause? U: every 2 waves.
23
- O: Facet scoring (planner facets → formula → band; facet gate: breadth + fan recomputed, risk cites checked):
24
- T1 3·new-surface·stateful·new-tests·fan0/3·low = 6+18+16+8+9 = 57 → sonnet-5-high (keystone — every later task imports its enum)
25
- T2 3·imitate·branching·new-tests·fan1/0·low = 6+8+8+8+5 = 35 → sonnet-4-6-med
26
- T3 3·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-4-6-med
27
- T4 2·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-4-6-med
28
- T5 1·mechanical·none·update-existing·fan0/0·low = 2+0+0+4 = 6 → haiku-4-5
29
- T6 1·mechanical·none·none·fan0/0·low = 2+0+0+0 = 2 → haiku-4-5
30
- Plan: 6 tasks, 3 waves W1{T1} W2{T2,T3,T4} W3{T5,T6}, all spawned. Anticipated escalations? U: none, go.
31
-
32
- ## Phase 3 — Execution (ALL spawned; orchestrator coordinates only)
33
- O: [checkpoint + state-of-play written into run/merchant-notifications/ BEFORE dispatch]
34
- ▶ W1: spawn Agent-A(T1, sonnet-5-high) — milestones 40%→100% — return validated ✓ (evidence: `yarn jest models/` exit 0, tail quoted; unmet[] empty) — log: DECISION type enum.
35
- ▶ W2: spawn 3 agents (sonnet-4-6-med each).
36
- Agent-C needs_context (1/2): "needs T1's enum interface" → O adjudicates in-scope → re-slices → resumes. (User never bothered.)
37
- Agent-C user escalation: "digest send time?" → U: 07:00 fixed → ANSWER broadcast to log.
38
- Returns validated ✓ · collision audit clean.
39
- ⏸ BATCH PAUSE (stop sequence):
40
- checkpoint ✓ → state-of-play ✓ → dispatch report shown (models/scores) → "Run /usage to see your remaining limits."
41
- → resume block:
42
- | Continue ORC run `merchant-notifications`.
43
- | Read run/merchant-notifications/state-of-play.md, then run/merchant-notifications/checkpoint.json.
44
- | Resume from checkpoint phase/wave. Intent-spec approved — do not re-plan. Do not redo done tasks.
45
- "Reply continue here, or paste in a fresh session (recommended if long)."
46
-
47
- U: [next day, FRESH session, pastes block]
48
- O: [state-of-play → checkpoint → re-anchored] "Resuming: merchant notifications (in-app+digest+prefs). Still correct?" U: yes.
49
- ▶ W3: spawn T5+T6 (haiku-4-5) → done. All 6 complete.
50
-
51
- ## Phase 5 — Review (spawned worker, Opus 5 medium)
52
- O: Code pattern? U: none. Findings (P0–P3 ladder, each P0–P2 anchored file:line + verbatim quote):
53
- P1 T2 no pagination — services/notification_list.ts:88 — O spot-checks: Reads line 88, quote matches ✓ → asks user, U: fix it
54
- · P3 email_digest naming ×2 · 12 tests added. (An unanchored finding would be auto-P3 — never fixed unasked.)
55
-
56
- ## Phase 6 — Verify (spawned worker, Opus 5 medium; criteria = definition-of-done)
57
- criteria[] with per-line evidence: bell ✓ (test name) · both schedules ✗ (weekly cron missing = P0, unmet criterion, evidence: no cron entry in scheduler.ts) · prefs ✓ → FAILED → quote spot-check ✓ → P0 auto-fix (single attempt, no ask) → re-verify → PASSED. 14/14.
58
-
59
- ## Phase 7 — Summary
60
- O: 6 tasks/3 waves/6 spawns/1 pause/1 fresh-session resume · 1 needs_context · 1 escalation · verify fixed_then_passed · branch green. P2 fix-batch: none · Apply the 2 P3 cosmetics? U: no.
61
-
62
- ## Phase 8 — Ship (orc-pr, reads pr.md)
63
- O: Branch: feat/notifications. Commit? Push? PR? U: yes all.
64
- O: Ticket/title/target? U: DRP-482 / Add merchant notification system / develop
65
- O: ✓ committed → pushed → run/merchant-notifications/DRP-482-add-merchant-notification-system.md from pr.md (base develop).
66
- Log deleted · checkpoint + dispatch log KEPT · completion dispatch report shown → "Run /usage to see your remaining limits."
67
-
68
- ## What this exercises
69
- always-spawn (even cheap tasks get a subagent) · facet-scored arithmetic · 6-band ladder ·
70
- per-run folder run/merchant-notifications/ · usage reminder (no programmatic /usage) ·
71
- planner grounding spot-check catching a hallucinated path · executor evidence (verbatim
72
- build/test proof) · reviewer quote spot-check before any P0/P1 action ·
73
- definition-of-done catching the weekly-cron gap · needs_context resolved internally · fresh-session resume.
1
+ # Example — Annotated Full Run (v2.2, dry run)
2
+
3
+ O: = orchestrator (Opus 4.8 high, always) · U: = user. Nothing real. The
4
+ orchestrator NEVER implements — it always spawns scored subagents.
5
+
6
+ U: Orchestrate: merchant notification system — in-app, email digest, prefs page.
7
+
8
+ ## Phase 0 — Intake
9
+ O: Creates run folder run/merchant-notifications/ FIRST.
10
+ [reads repo: TS/yarn/jest — asks nothing about stack] Rough size: medium+ → 4-question tier (one batched round):
11
+ 1) What should exist when done? 2) Out of scope? 3) How do we know it's done? 4) Patterns/files to avoid?
12
+ U: [answers] no push, no admin; bell count + both digest schedules + prefs persist; follow services/ pattern, don't touch auth_service.
13
+ O: [drafts run/merchant-notifications/intent-spec.md] Sign-off: gate or soft? (default gate)
14
+ U: gate → approved
15
+
16
+ ## Phase 1 — Planning
17
+ O: Planner? U: OpenSpec
18
+ O: [6 tasks with declared_files incl. tests + per-file grounding attestations + sliced acceptance[], depends_on, spec_ref] ⚠ T1/T2 share models/notification.ts → scheduling separates them.
19
+ Grounding spot-check (Phase 1 exit): globs all `exists` paths — 13/14 present, models/notifcation.ts MISSING (typo) → plan bounced to planner with the miss list → corrected to models/notification.ts ✓.
20
+
21
+ ## Phase 2 — Effort, dispatch style, scoring
22
+ O: Refined: medium, partially dependent. Recommend PARALLEL waves. Confirm? U: yes. Batch pause? U: every 2 waves.
23
+ O: Facet scoring (planner facets → formula → band; facet gate: breadth + fan recomputed, risk cites checked):
24
+ T1 3·new-surface·stateful·new-tests·fan0/3·low = 6+18+16+8+9 = 57 → sonnet-5-high (keystone — every later task imports its enum)
25
+ T2 3·imitate·branching·new-tests·fan1/0·low = 6+8+8+8+5 = 35 → sonnet-4-6-med
26
+ T3 3·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-4-6-med
27
+ T4 2·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-4-6-med
28
+ T5 1·mechanical·none·update-existing·fan0/0·low = 2+0+0+4 = 6 → haiku-4-5
29
+ T6 1·mechanical·none·none·fan0/0·low = 2+0+0+0 = 2 → haiku-4-5
30
+ Plan: 6 tasks, 3 waves W1{T1} W2{T2,T3,T4} W3{T5,T6}, all spawned. Anticipated escalations? U: none, go.
31
+
32
+ ## Phase 3 — Execution (ALL spawned; orchestrator coordinates only)
33
+ O: [checkpoint + state-of-play written into run/merchant-notifications/ BEFORE dispatch]
34
+ ▶ W1: spawn Agent-A(T1, sonnet-5-high) — milestones 40%→100% — return validated ✓ (evidence: `yarn jest models/` exit 0, tail quoted; unmet[] empty) — log: DECISION type enum.
35
+ ▶ W2: spawn 3 agents (sonnet-4-6-med each).
36
+ Agent-C needs_context (1/2): "needs T1's enum interface" → O adjudicates in-scope → re-slices → resumes. (User never bothered.)
37
+ Agent-C user escalation: "digest send time?" → U: 07:00 fixed → ANSWER broadcast to log.
38
+ Returns validated ✓ · collision audit clean.
39
+ ⏸ BATCH PAUSE (stop sequence):
40
+ checkpoint ✓ → state-of-play ✓ → dispatch report shown (models/scores) → "Run /usage to see your remaining limits."
41
+ → resume block:
42
+ | Continue ORC run `merchant-notifications`.
43
+ | Read run/merchant-notifications/state-of-play.md, then run/merchant-notifications/checkpoint.json.
44
+ | Resume from checkpoint phase/wave. Intent-spec approved — do not re-plan. Do not redo done tasks.
45
+ "Reply continue here, or paste in a fresh session (recommended if long)."
46
+
47
+ U: [next day, FRESH session, pastes block]
48
+ O: [state-of-play → checkpoint → re-anchored] "Resuming: merchant notifications (in-app+digest+prefs). Still correct?" U: yes.
49
+ ▶ W3: spawn T5+T6 (haiku-4-5) → done. All 6 complete.
50
+
51
+ ## Phase 5 — Review (spawned worker, Opus 5.5 medium)
52
+ O: Code pattern? U: none. Findings (P0–P3 ladder, each P0–P2 anchored file:line + verbatim quote):
53
+ P1 T2 no pagination — services/notification_list.ts:88 — O spot-checks: Reads line 88, quote matches ✓ → asks user, U: fix it
54
+ · P3 email_digest naming ×2 · 12 tests added. (An unanchored finding would be auto-P3 — never fixed unasked.)
55
+
56
+ ## Phase 6 — Verify (spawned worker, Opus 5.5 medium; criteria = definition-of-done)
57
+ criteria[] with per-line evidence: bell ✓ (test name) · both schedules ✗ (weekly cron missing = P0, unmet criterion, evidence: no cron entry in scheduler.ts) · prefs ✓ → FAILED → quote spot-check ✓ → P0 auto-fix (single attempt, no ask) → re-verify → PASSED. 14/14.
58
+
59
+ ## Phase 7 — Summary
60
+ O: 6 tasks/3 waves/6 spawns/1 pause/1 fresh-session resume · 1 needs_context · 1 escalation · verify fixed_then_passed · branch green. P2 fix-batch: none · Apply the 2 P3 cosmetics? U: no.
61
+
62
+ ## Phase 8 — Ship (orc-pr, reads pr.md)
63
+ O: Branch: feat/notifications. Commit? Push? PR? U: yes all.
64
+ O: Ticket/title/target? U: DRP-482 / Add merchant notification system / develop
65
+ O: ✓ committed → pushed → run/merchant-notifications/DRP-482-add-merchant-notification-system.md from pr.md (base develop).
66
+ Log deleted · checkpoint + dispatch log KEPT · completion dispatch report shown → "Run /usage to see your remaining limits."
67
+
68
+ ## What this exercises
69
+ always-spawn (even cheap tasks get a subagent) · facet-scored arithmetic · 6-band ladder ·
70
+ per-run folder run/merchant-notifications/ · usage reminder (no programmatic /usage) ·
71
+ planner grounding spot-check catching a hallucinated path · executor evidence (verbatim
72
+ build/test proof) · reviewer quote spot-check before any P0/P1 action ·
73
+ definition-of-done catching the weekly-cron gap · needs_context resolved internally · fresh-session resume.