@azure-id/orc 2.1.0 → 2.2.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 +374 -0
  2. package/README.md +49 -36
  3. package/bin/build-agents.js +7 -5
  4. package/bin/cli.js +1006 -235
  5. package/bin/fix.js +21 -18
  6. package/bin/graph-extract.js +314 -6
  7. package/bin/graph-gain.js +83 -2
  8. package/bin/graph-map.js +23 -1
  9. package/bin/graph-notes.js +1 -1
  10. package/bin/graph-query.js +1362 -37
  11. package/bin/graph-resolve.js +1 -1
  12. package/bin/graph-shard.js +29 -6
  13. package/bin/graph-signals.js +5 -3
  14. package/bin/graph.js +7 -3
  15. package/bin/habit.js +1 -1
  16. package/bin/pricing.json +8 -1
  17. package/bin/trace-write.js +40 -11
  18. package/bin/verify-contracts.js +169 -60
  19. package/bin/verify-package.js +3 -3
  20. package/bin/webui/api.js +8 -0
  21. package/bin/webui/fixtures/extra.js +9 -9
  22. package/bin/webui/fixtures/flow.js +1 -1
  23. package/bin/webui/fixtures/index.js +2 -2
  24. package/bin/webui/fixtures/knowledge.js +8 -1
  25. package/bin/webui/fixtures/pact.js +112 -111
  26. package/bin/webui/fixtures/stats.js +2 -2
  27. package/bin/webui/i18n/en/knowledge.json +2 -0
  28. package/bin/webui/i18n/id/knowledge.json +2 -0
  29. package/bin/webui/js/panels/knowledge.js +17 -0
  30. package/guides/code-graph-benefit.md +116 -0
  31. package/guides/configuration.md +150 -0
  32. package/guides/documents.md +262 -0
  33. package/guides/extra-models.md +448 -0
  34. package/guides/habits-and-gotchas.md +152 -0
  35. package/guides/knowledge-reads.md +190 -0
  36. package/guides/model-selection.md +186 -0
  37. package/guides/rules.md +305 -0
  38. package/guides/status-line.md +344 -0
  39. package/mock-run/a-normal-day.md +2 -2
  40. package/mock-run/extra-slots.md +177 -177
  41. package/mock-run/orc-cli.md +3 -2
  42. package/mock-run/orc-doc.md +452 -448
  43. package/mock-run/orc-fast.md +2 -2
  44. package/mock-run/orc-quick.md +146 -146
  45. package/mock-run/orc.md +4 -4
  46. package/package.json +2 -1
  47. package/templates/agents/MODEL-MAPPING.md +12 -12
  48. package/templates/agents/{orc-executor-haiku-4-5.md → orc-executor-haiku-5-high.md} +21 -8
  49. package/templates/agents/orc-executor-opus-4-7-high.md +17 -5
  50. package/templates/agents/orc-executor-opus-4-7-med.md +17 -5
  51. package/templates/agents/orc-executor-opus-4-8-high.md +17 -5
  52. package/templates/agents/orc-executor-opus-5-high.md +17 -5
  53. package/templates/agents/orc-executor-opus-5-low.md +17 -5
  54. package/templates/agents/orc-executor-opus-5-med.md +17 -5
  55. package/templates/agents/orc-executor-sonnet-4-6-high.md +17 -5
  56. package/templates/agents/orc-executor-sonnet-5-high.md +17 -5
  57. package/templates/agents/orc-executor-sonnet-5-low.md +17 -5
  58. package/templates/agents/orc-executor-sonnet-5-med.md +17 -5
  59. package/templates/agents/{orc-graph-noter-sonnet-4-6-med.md → orc-graph-noter-haiku-5-high.md} +4 -4
  60. package/templates/agents/orc-planner-mini-opus-5-med.md +3 -1
  61. package/templates/agents/orc-planner-mini-sonnet-5-high.md +3 -1
  62. package/templates/agents/orc-planner-opus-5-med.md +3 -1
  63. package/templates/agents/{orc-recon-sonnet-4-6-med.md → orc-recon-sonnet-5-med.md} +4 -4
  64. package/templates/agents/{orc-trace-writer-haiku-4-5.md → orc-trace-writer-haiku-5-high.md} +4 -3
  65. package/templates/commands/orc-doc.md +128 -128
  66. package/templates/commands/orc-export.md +51 -46
  67. package/templates/commands/orc-fast.md +10 -10
  68. package/templates/hooks/README.md +8 -3
  69. package/templates/hooks/orc-effort-guard.js +105 -27
  70. package/templates/hooks/orc-graph-hook.js +252 -4
  71. package/templates/hooks/orc-statusline.js +13 -6
  72. package/templates/hooks/orc-trace.js +1 -1
  73. package/templates/skills/_shared/README.md +2 -2
  74. package/templates/skills/_shared/code-graph.md +185 -251
  75. package/templates/skills/_shared/extra-dispatch.md +4 -4
  76. package/templates/skills/_shared/lane-contract.md +7 -3
  77. package/templates/skills/_shared/opus5-only.md +3 -3
  78. package/templates/skills/_shared/phases/execution.md +13 -11
  79. package/templates/skills/_shared/phases/planning.md +27 -9
  80. package/templates/skills/_shared/phases/preflight.md +3 -3
  81. package/templates/skills/_shared/phases/review.md +4 -3
  82. package/templates/skills/_shared/phases/ship.md +7 -10
  83. package/templates/skills/_shared/phases/summary.md +2 -3
  84. package/templates/skills/_shared/phases/trace-verbs.md +21 -16
  85. package/templates/skills/_shared/phases/trace.md +3 -3
  86. package/templates/skills/_shared/phases/wiki-consult.md +2 -2
  87. package/templates/skills/_shared/pr-templates.md +108 -106
  88. package/templates/skills/_shared/read-ladder.md +8 -2
  89. package/templates/skills/_shared/return-validation.md +10 -6
  90. package/templates/skills/_shared/review-slice.md +1 -1
  91. package/templates/skills/_shared/stack-plan.md +135 -135
  92. package/templates/skills/_shared/wait.md +14 -2
  93. package/templates/skills/context-combiner/SKILL.md +2 -2
  94. package/templates/skills/orc/SKILL.md +7 -7
  95. package/templates/skills/orc/config.md +2 -2
  96. package/templates/skills/orc/examples/full-run-mock.md +7 -7
  97. package/templates/skills/orc/references/effort-and-mode.md +222 -222
  98. package/templates/skills/orc/schemas/planning-output.md +3 -0
  99. package/templates/skills/orc-aftermath/SKILL.md +15 -15
  100. package/templates/skills/orc-analyze/SKILL.md +2 -2
  101. package/templates/skills/orc-analyze-mini/SKILL.md +2 -2
  102. package/templates/skills/orc-boundary/SKILL.md +15 -15
  103. package/templates/skills/orc-boundary/references/card.md +81 -78
  104. package/templates/skills/orc-boundary/references/gate.md +113 -113
  105. package/templates/skills/orc-brainstorm/SKILL.md +15 -15
  106. package/templates/skills/orc-budget/SKILL.md +15 -15
  107. package/templates/skills/orc-challenge/README.md +1 -1
  108. package/templates/skills/orc-challenge/SKILL.md +16 -16
  109. package/templates/skills/orc-challenge/examples/council-full-roster.md +1 -1
  110. package/templates/skills/orc-claude/SKILL.md +4 -4
  111. package/templates/skills/orc-claude/examples/claude-run-mock.md +1 -1
  112. package/templates/skills/orc-diy/SKILL.md +2 -2
  113. package/templates/skills/orc-diy/references/blocks/wiki.md +26 -26
  114. package/templates/skills/orc-diy/references/flow-schema.md +2 -2
  115. package/templates/skills/orc-doc/README.md +2 -2
  116. package/templates/skills/orc-doc/SKILL.md +501 -490
  117. package/templates/skills/orc-doc/examples/orc-doc-prd-run.md +12 -1
  118. package/templates/skills/orc-doc/references/chunking.md +6 -4
  119. package/templates/skills/orc-doc/references/gates.md +311 -311
  120. package/templates/skills/orc-doc/references/resume-protocol.md +229 -228
  121. package/templates/skills/orc-explain/SKILL.md +88 -88
  122. package/templates/skills/orc-export/SKILL.md +190 -187
  123. package/templates/skills/orc-fast/SKILL.md +17 -14
  124. package/templates/skills/orc-grill/SKILL.md +16 -16
  125. package/templates/skills/orc-grill/references/grill-doc.md +1 -1
  126. package/templates/skills/orc-handoff/SKILL.md +11 -11
  127. package/templates/skills/orc-learn/SKILL.md +13 -13
  128. package/templates/skills/orc-learn/examples/learn-run-mock.md +2 -2
  129. package/templates/skills/orc-mini/SKILL.md +12 -12
  130. package/templates/skills/orc-mini/examples/mini-run-mock.md +4 -5
  131. package/templates/skills/orc-pact/SKILL.md +15 -15
  132. package/templates/skills/orc-pact/references/gate.md +70 -70
  133. package/templates/skills/orc-pattern/SKILL.md +3 -3
  134. package/templates/skills/orc-poly/SKILL.md +4 -4
  135. package/templates/skills/orc-poly/examples/poly-run-mock.md +51 -51
  136. package/templates/skills/orc-pr-driver/SKILL.md +4 -3
  137. package/templates/skills/orc-pr-driver/references/orc-run-split.md +108 -99
  138. package/templates/skills/orc-pr-setup/SKILL.md +2 -2
  139. package/templates/skills/orc-quick/README.md +11 -12
  140. package/templates/skills/orc-quick/SKILL.md +29 -32
  141. package/templates/skills/orc-quick/references/context-doc.md +5 -5
  142. package/templates/skills/orc-quick/references/dispatch-gate.md +10 -10
  143. package/templates/skills/orc-quick/references/gh-mode.md +2 -1
  144. package/templates/skills/orc-quick/references/look.md +34 -12
  145. package/templates/skills/orc-retro/SKILL.md +2 -2
  146. package/templates/skills/orc-retro/examples/retro-mock.md +2 -2
  147. package/templates/skills/orc-route/SKILL.md +2 -2
  148. package/templates/skills/orc-test/SKILL.md +6 -3
  149. package/templates/skills/orc-verify/SKILL.md +2 -2
  150. package/templates/skills/orc-wait/SKILL.md +10 -2
  151. package/templates/skills/orc-wiki/SKILL.md +4 -4
  152. package/templates/skills/orc-wiki/references/pattern-prewarm.md +19 -19
  153. package/templates/agents/orc-executor-sonnet-4-6-med.md +0 -155
@@ -235,22 +235,22 @@ documented defaults, out loud. Priorities and families:
235
235
  ## Calls
236
236
 
237
237
  **ONE catalogue, and it is not you:** `orc lane calls orc-boundary --json` names every
238
- CLI call this lane makes, each with its exit-code contract, its cost, when to run
238
+ SHARED CLI call this lane makes, each with its exit-code contract, its cost, when to run
239
239
  it, and what an EMPTY answer means. Never invent a spelling, never re-word an
240
240
  exit code, and never re-derive a state word — the CLI's state words are the only
241
241
  state words, and **an exit code is an ANSWER wherever that contract says so, not
242
- a failure**. A call the answer does not name is a call this lane does not make.
242
+ a failure**. A call that neither it nor this skill names is a call this lane does not make.
243
243
  Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
244
- command you are about to run, out loud, before running it.
245
-
246
- ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
247
-
248
- `orc rules slice --lane orc-boundary --json` is the ONLY assembler; never build
249
- the card here. It rides under the house rules and above the task —
250
- **house rules > your project's rules > ORC's own packs** — and its `line` prints
251
- VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
252
- never a silent choice) and `rules_overridden[]`.
253
- ## Waiting mid-run (`/orc-wait`)
254
-
255
- Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
256
- Checkpoint **none** · safe point **read-only, seconds long**. 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.
244
+ command you are about to run, out loud, before running it.
245
+
246
+ ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
247
+
248
+ `orc rules slice --lane orc-boundary --json` is the ONLY assembler; never build
249
+ the card here. It rides under the house rules and above the task —
250
+ **house rules > your project's rules > ORC's own packs** — and its `line` prints
251
+ VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
252
+ never a silent choice) and `rules_overridden[]`.
253
+ ## Waiting mid-run (`/orc-wait`)
254
+
255
+ Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
256
+ Checkpoint **none** · safe point **read-only, seconds long**. 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.
@@ -1,78 +1,81 @@
1
- # Reference — the boundary card
2
-
3
- Loaded at B4. One file per area: `.claude/orc/boundary/<area-slug>.md`. The slug
4
- is the area path with `/` → `-` (`src/payments` → `src-payments.md`), the same
5
- sanitisation `wiki/crosslink/<kind>/` uses — a nested path a single-level readdir
6
- never sees is a card that is invisible with the status check still green.
7
-
8
- ## Shape
9
-
10
- ```markdown
11
- ---
12
- area: src/payments # verbatim — this is the identity
13
- verdict: EXECUTE | ESCALATE | REFUSE
14
- anchored_files: # what staleness is computed against
15
- - src/payments/ledger.ts
16
- - src/payments/idempotency.ts
17
- verified_commit: 8a62b4f # HEAD when the four questions were answered
18
- scanned_at: 100826 14:11:30
19
- reasons: # the four answers, compressed. Required.
20
- - "self-verify: no — no test runner in this package"
21
- - "reversible: no — writes to a live ledger"
22
- checklist: # REQUIRED when verdict is REFUSE
23
- - add a test runner to this package
24
- - cover the idempotency path
25
- escalate_to: "the payments owner" # REQUIRED when verdict is ESCALATE
26
- ---
27
-
28
- # src/payments — REFUSE
29
-
30
- ## Why
31
- <the derivation, in prose. Two or three sentences.>
32
-
33
- ## What would make this a yes
34
- <the checklist again, with the lane that clears each item named.>
35
-
36
- ## What an agent MAY do here today
37
- <the part that is fine. A card that reads as "hands off entirely" when only one
38
- file is dangerous costs more than it saves.>
39
- ```
40
-
41
- ## Field rules
42
-
43
- **`area`** — verbatim, never sanitised. The filename is sanitised; the identity is
44
- not. Same split as a crosslink kind.
45
-
46
- **`anchored_files`** — the files whose change should make this verdict
47
- re-examined. Over-broad (`src/**`) makes every card permanently stale; empty makes
48
- every card permanently fresh. Both defeat the point.
49
-
50
- **`verified_commit`** — HEAD at the moment the four questions were answered. Moved
51
- only by a real re-examination, never bumped to quiet a stale flag.
52
-
53
- **`reasons`** — at least the answers that DROVE the verdict. This is what makes a
54
- verdict arguable, and a verdict nobody can argue with is one people route around.
55
-
56
- **`checklist`** — required on REFUSE, and each item must be a thing somebody could
57
- actually finish. "Be more careful" is not a checklist item. Where another lane
58
- clears it, name the lane (`→ /orc-pact`, `→ /orc-pattern`).
59
-
60
- **`escalate_to`** — required on ESCALATE. A role is fine ("the payments owner"); a
61
- shrug is not.
62
-
63
- ## The last section is not optional
64
-
65
- **"What an agent MAY do here today"** is what stops a card from reading as a wall.
66
- Most REFUSE areas contain plenty of safe work — tests, docs, a rename, a log line.
67
- A card that does not say so gets ignored, and an ignored card is worse than none,
68
- because it looks like coverage.
69
-
70
- ## Staleness
71
-
72
- Computed on read by `orc boundary status`, never stored:
73
- `git rev-list --count <verified_commit>..HEAD -- <anchored_files>`. Non-zero =
74
- stale. **The skill never computes this** — same rule as the wiki tier
75
- (`../../_shared/detecting-artifacts.md`).
76
-
77
- A stale card is not a wrong card; it is one whose evidence has moved. Refresh is
78
- cheap: re-run the four questions for that area only.
1
+ # Reference — the boundary card
2
+
3
+ Loaded at B4. One file per area: `.claude/orc/boundary/<area-slug>.md`. The slug
4
+ is the area path with `/` → `-` (`src/payments` → `src-payments.md`), the same
5
+ sanitisation `wiki/crosslink/<kind>/` uses — a nested path a single-level readdir
6
+ never sees is a card that is invisible with the status check still green.
7
+
8
+ ## Shape
9
+
10
+ ```markdown
11
+ ---
12
+ area: src/payments # verbatim — this is the identity
13
+ verdict: EXECUTE | ESCALATE | REFUSE
14
+ anchored_files: # what staleness is computed against
15
+ - src/payments/ledger.ts
16
+ - src/payments/idempotency.ts
17
+ verified_commit: 8a62b4f # HEAD when the four questions were answered
18
+ scanned_at: 100826 14:11:30
19
+ reasons: # the four answers, compressed. Required.
20
+ - "self-verify: no — no test runner in this package"
21
+ - "reversible: no — writes to a live ledger"
22
+ checklist: # REQUIRED when verdict is REFUSE
23
+ - add a test runner to this package
24
+ - cover the idempotency path
25
+ escalate_to: "the payments owner" # REQUIRED when verdict is ESCALATE
26
+ ---
27
+
28
+ # src/payments — REFUSE
29
+
30
+ ## Why
31
+ <the derivation, in prose. Two or three sentences.>
32
+
33
+ ## What would make this a yes
34
+ <the checklist again, with the lane that clears each item named.>
35
+
36
+ ## What an agent MAY do here today
37
+ <the part that is fine. A card that reads as "hands off entirely" when only one
38
+ file is dangerous costs more than it saves.>
39
+ ```
40
+
41
+ Lists may be block (`- item`) or inline (`[a, b]`). `orc boundary status` reads
42
+ both (v2.1.2). An item that holds a comma or a `#` goes in quotes.
43
+
44
+ ## Field rules
45
+
46
+ **`area`** — verbatim, never sanitised. The filename is sanitised; the identity is
47
+ not. Same split as a crosslink kind.
48
+
49
+ **`anchored_files`** — the files whose change should make this verdict
50
+ re-examined. Over-broad (`src/**`) makes every card permanently stale; empty makes
51
+ every card permanently fresh. Both defeat the point.
52
+
53
+ **`verified_commit`** — HEAD at the moment the four questions were answered. Moved
54
+ only by a real re-examination, never bumped to quiet a stale flag.
55
+
56
+ **`reasons`** — at least the answers that DROVE the verdict. This is what makes a
57
+ verdict arguable, and a verdict nobody can argue with is one people route around.
58
+
59
+ **`checklist`** — required on REFUSE, and each item must be a thing somebody could
60
+ actually finish. "Be more careful" is not a checklist item. Where another lane
61
+ clears it, name the lane (`→ /orc-pact`, `→ /orc-pattern`).
62
+
63
+ **`escalate_to`** — required on ESCALATE. A role is fine ("the payments owner"); a
64
+ shrug is not.
65
+
66
+ ## The last section is not optional
67
+
68
+ **"What an agent MAY do here today"** is what stops a card from reading as a wall.
69
+ Most REFUSE areas contain plenty of safe work — tests, docs, a rename, a log line.
70
+ A card that does not say so gets ignored, and an ignored card is worse than none,
71
+ because it looks like coverage.
72
+
73
+ ## Staleness
74
+
75
+ Computed on read by `orc boundary status`, never stored:
76
+ `git rev-list --count <verified_commit>..HEAD -- <anchored_files>`. Non-zero =
77
+ stale. **The skill never computes this** — same rule as the wiki tier
78
+ (`../../_shared/detecting-artifacts.md`).
79
+
80
+ A stale card is not a wrong card; it is one whose evidence has moved. Refresh is
81
+ cheap: re-run the four questions for that area only.
@@ -1,113 +1,113 @@
1
- # Reference — the boundary gate inside `/orc` (`boundary_gate`)
2
-
3
- Loaded by the spine at Phase 1. This is the CONSUMER half: `/orc` reads cards, it
4
- never writes one.
5
-
6
- `boundary_gate: off | warn | block` — default **`warn`**.
7
-
8
- | Mode | What changes |
9
- |---|---|
10
- | `off` | nothing. Cards are ignored entirely. |
11
- | `warn` | the preflight line, plus a per-task verdict printed before each wave. No dispatch changes. |
12
- | `block` | additionally: a REFUSE task is LIFTED OUT of its wave and never dispatched. |
13
-
14
- `block` changes dispatch behaviour on upgrade, which is why it is not the default.
15
- Print the active mode whenever a verdict is shown — a gate whose mode is invisible
16
- gets blamed for things it did not do.
17
-
18
- ## Phase 1 — preflight, one line
19
-
20
- `orc boundary status --json` with the other probes. Print the `line` field
21
- VERBATIM:
22
-
23
- ```
24
- bound : 9 execute · 2 escalate · 1 refuse (2 stale)
25
- ```
26
-
27
- Never re-word it, never compute the counts. No cards at all:
28
-
29
- ```
30
- bound : none — /orc-boundary writes them; no card means an area is UNKNOWN, not safe
31
- ```
32
-
33
- ## Phase 3 — per wave
34
-
35
- Before dispatching wave W, resolve each task's area by matching its
36
- `declared_files` against every card's `anchored_files` (longest match wins), then:
37
-
38
- **EXECUTE** — dispatch normally. Nothing printed beyond the wave table.
39
-
40
- **ESCALATE** — dispatch normally, and record the named human on the task. **Ship
41
- is gated on that sign-off**, using the EXISTING pause machinery — the stop sequence
42
- at the wave boundary, with the escalation named in the stop reason. No new stop
43
- mechanic, no new config key.
44
-
45
- **REFUSE** —
46
-
47
- - `warn`: print the verdict and its checklist, then dispatch anyway. The user was
48
- told; the run is theirs.
49
- - `block`: **lift that ONE task out of the wave. The wave proceeds with the
50
- rest.** Blocking the whole wave punishes the tasks that were fine, and a gate
51
- that costs a wave gets switched off. Print:
52
-
53
- ```
54
- boundary → wave 2: T04 lifted out (REFUSE · src/payments)
55
- the wave runs with T03, T05.
56
- T04 comes back when:
57
- □ add a test runner to this package
58
- □ cover the idempotency path → /orc-pattern
59
- Not blocked for you — say "do T04 anyway" and it dispatches.
60
- ```
61
-
62
- That last line is required. The gate constrains ORC, not the user.
63
-
64
- A lifted task's dependents are **requeued, not cancelled**: the existing
65
- `REPLAN wave=<n>` path already handles a task that did not land, and this is that
66
- case with a different cause.
67
-
68
- **A task in an area with NO card** is dispatched normally and reported as
69
- `boundary: unknown` on its dispatch line. Unknown is not REFUSE — refusing
70
- everything uncarded would make the first run after install useless.
71
-
72
- ### Extra — a REFUSE area never goes foreign, in either mode
73
-
74
- A task whose area is **REFUSE never routes to a non-Claude worker** whatever the
75
- route table says (`extra_enabled`, `../../_shared/extra-dispatch.md`), and this
76
- holds in `warn` mode too — where the task still dispatches, but to Claude. It is
77
- the second hard hold-back beside the cited-risk one, and it is deliberately
78
- *wider* than the `block` mode it sits next to.
79
-
80
- The reason is that the two verdicts are answering different questions. `block`
81
- decides whether ORC should attempt the task at all, and `warn` says the user
82
- accepted that risk. Neither of them asked whether the work should leave the
83
- machine — and a REFUSE is, by construction, an area where ORC **cannot verify
84
- its own output** (that is one of the four questions the verdict is derived from).
85
- Handing exactly that work to the executor with the weakest fence and no
86
- `actual_model` line compounds the one condition the card was written about.
87
-
88
- Print it with the verdict, and name it in the `extra:` preflight's held-back
89
- count. **A card that caused a hold-back must say so on its own card**, so the
90
- next reader learns it from the boundary lane rather than from a routing table
91
- they were not looking at. `unknown` is not REFUSE here either — an uncarded area
92
- routes by the ordinary rules.
93
-
94
- ## `/orc-route`
95
-
96
- A plan with any REFUSE task **cannot route to `/orc-fast`**: fast has one executor
97
- and no wave to lift anything out of, so the gate has nowhere to act. Report it in
98
- the not-possible column with the verdict named, exactly like the other blocking
99
- conditions.
100
-
101
- ## `/orc-ultra`
102
-
103
- The implementation judge may score against the area's card: an implementation that
104
- did the REFUSE-listed thing anyway is a blocking finding with an anchor
105
- (`.claude/orc/boundary/<area>.md`) and a consequence already written down.
106
-
107
- ## The trace verb
108
-
109
- `BOUNDARY <verdict> task=<id> :: <area>` per gated task, and
110
- `BOUNDARY lift task=<id> :: <area>` when `block` removes one. Carried in the phase
111
- packet like every other verb — handed to `orc-trace-writer-haiku-4-5`, never
112
- written directly. `/orc-retro` reads them to answer the question this whole lane
113
- exists for: how much work did we stop attempting, and was that right?
1
+ # Reference — the boundary gate inside `/orc` (`boundary_gate`)
2
+
3
+ Loaded by the spine at Phase 1. This is the CONSUMER half: `/orc` reads cards, it
4
+ never writes one.
5
+
6
+ `boundary_gate: off | warn | block` — default **`warn`**.
7
+
8
+ | Mode | What changes |
9
+ |---|---|
10
+ | `off` | nothing. Cards are ignored entirely. |
11
+ | `warn` | the preflight line, plus a per-task verdict printed before each wave. No dispatch changes. |
12
+ | `block` | additionally: a REFUSE task is LIFTED OUT of its wave and never dispatched. |
13
+
14
+ `block` changes dispatch behaviour on upgrade, which is why it is not the default.
15
+ Print the active mode whenever a verdict is shown — a gate whose mode is invisible
16
+ gets blamed for things it did not do.
17
+
18
+ ## Phase 1 — preflight, one line
19
+
20
+ `orc boundary status --json` with the other probes. Print the `line` field
21
+ VERBATIM:
22
+
23
+ ```
24
+ bound : 9 execute · 2 escalate · 1 refuse (2 stale)
25
+ ```
26
+
27
+ Never re-word it, never compute the counts. No cards at all:
28
+
29
+ ```
30
+ bound : none — /orc-boundary writes them; no card means an area is UNKNOWN, not safe
31
+ ```
32
+
33
+ ## Phase 3 — per wave
34
+
35
+ Before dispatching wave W, resolve each task's area by matching its
36
+ `declared_files` against every card's `anchored_files` (longest match wins), then:
37
+
38
+ **EXECUTE** — dispatch normally. Nothing printed beyond the wave table.
39
+
40
+ **ESCALATE** — dispatch normally, and record the named human on the task. **Ship
41
+ is gated on that sign-off**, using the EXISTING pause machinery — the stop sequence
42
+ at the wave boundary, with the escalation named in the stop reason. No new stop
43
+ mechanic, no new config key.
44
+
45
+ **REFUSE** —
46
+
47
+ - `warn`: print the verdict and its checklist, then dispatch anyway. The user was
48
+ told; the run is theirs.
49
+ - `block`: **lift that ONE task out of the wave. The wave proceeds with the
50
+ rest.** Blocking the whole wave punishes the tasks that were fine, and a gate
51
+ that costs a wave gets switched off. Print:
52
+
53
+ ```
54
+ boundary → wave 2: T04 lifted out (REFUSE · src/payments)
55
+ the wave runs with T03, T05.
56
+ T04 comes back when:
57
+ □ add a test runner to this package
58
+ □ cover the idempotency path → /orc-pattern
59
+ Not blocked for you — say "do T04 anyway" and it dispatches.
60
+ ```
61
+
62
+ That last line is required. The gate constrains ORC, not the user.
63
+
64
+ A lifted task's dependents are **requeued, not cancelled**: the existing
65
+ `REPLAN wave=<n>` path already handles a task that did not land, and this is that
66
+ case with a different cause.
67
+
68
+ **A task in an area with NO card** is dispatched normally and reported as
69
+ `boundary: unknown` on its dispatch line. Unknown is not REFUSE — refusing
70
+ everything uncarded would make the first run after install useless.
71
+
72
+ ### Extra — a REFUSE area never goes foreign, in either mode
73
+
74
+ A task whose area is **REFUSE never routes to a non-Claude worker** whatever the
75
+ route table says (`extra_enabled`, `../../_shared/extra-dispatch.md`), and this
76
+ holds in `warn` mode too — where the task still dispatches, but to Claude. It is
77
+ the second hard hold-back beside the cited-risk one, and it is deliberately
78
+ *wider* than the `block` mode it sits next to.
79
+
80
+ The reason is that the two verdicts are answering different questions. `block`
81
+ decides whether ORC should attempt the task at all, and `warn` says the user
82
+ accepted that risk. Neither of them asked whether the work should leave the
83
+ machine — and a REFUSE is, by construction, an area where ORC **cannot verify
84
+ its own output** (that is one of the four questions the verdict is derived from).
85
+ Handing exactly that work to the executor with the weakest fence and no
86
+ `actual_model` line compounds the one condition the card was written about.
87
+
88
+ Print it with the verdict, and name it in the `extra:` preflight's held-back
89
+ count. **A card that caused a hold-back must say so on its own card**, so the
90
+ next reader learns it from the boundary lane rather than from a routing table
91
+ they were not looking at. `unknown` is not REFUSE here either — an uncarded area
92
+ routes by the ordinary rules.
93
+
94
+ ## `/orc-route`
95
+
96
+ A plan with any REFUSE task **cannot route to `/orc-fast`**: fast has one executor
97
+ and no wave to lift anything out of, so the gate has nowhere to act. Report it in
98
+ the not-possible column with the verdict named, exactly like the other blocking
99
+ conditions.
100
+
101
+ ## `/orc-ultra`
102
+
103
+ The implementation judge may score against the area's card: an implementation that
104
+ did the REFUSE-listed thing anyway is a blocking finding with an anchor
105
+ (`.claude/orc/boundary/<area>.md`) and a consequence already written down.
106
+
107
+ ## The trace verb
108
+
109
+ `BOUNDARY <verdict> task=<id> :: <area>` per gated task, and
110
+ `BOUNDARY lift task=<id> :: <area>` when `block` removes one. Carried in the phase
111
+ packet like every other verb — handed to `orc-trace-writer-haiku-5-high`, never
112
+ written directly. `/orc-retro` reads them to answer the question this whole lane
113
+ exists for: how much work did we stop attempting, and was that right?
@@ -363,22 +363,22 @@ preflight line and has no gate to honour.
363
363
  ## Calls
364
364
 
365
365
  **ONE catalogue, and it is not you:** `orc lane calls orc-brainstorm --json` names every
366
- CLI call this lane makes, each with its exit-code contract, its cost, when to run
366
+ SHARED CLI call this lane makes, each with its exit-code contract, its cost, when to run
367
367
  it, and what an EMPTY answer means. Never invent a spelling, never re-word an
368
368
  exit code, and never re-derive a state word — the CLI's state words are the only
369
369
  state words, and **an exit code is an ANSWER wherever that contract says so, not
370
- a failure**. A call the answer does not name is a call this lane does not make.
370
+ a failure**. A call that neither it nor this skill names is a call this lane does not make.
371
371
  Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
372
- command you are about to run, out loud, before running it.
373
-
374
- ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
375
-
376
- `orc rules slice --lane orc-brainstorm --json` is the ONLY assembler; never build
377
- the card here. It rides under the house rules and above the task —
378
- **house rules > your project's rules > ORC's own packs** — and its `line` prints
379
- VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
380
- never a silent choice) and `rules_overridden[]`.
381
- ## Waiting mid-run (`/orc-wait`)
382
-
383
- Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
384
- Checkpoint **snapshot** · safe point **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.
372
+ command you are about to run, out loud, before running it.
373
+
374
+ ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
375
+
376
+ `orc rules slice --lane orc-brainstorm --json` is the ONLY assembler; never build
377
+ the card here. It rides under the house rules and above the task —
378
+ **house rules > your project's rules > ORC's own packs** — and its `line` prints
379
+ VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
380
+ never a silent choice) and `rules_overridden[]`.
381
+ ## Waiting mid-run (`/orc-wait`)
382
+
383
+ Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
384
+ Checkpoint **snapshot** · safe point **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.
@@ -234,22 +234,22 @@ preflight line and has no gate to honour.
234
234
  ## Calls
235
235
 
236
236
  **ONE catalogue, and it is not you:** `orc lane calls orc-budget --json` names every
237
- CLI call this lane makes, each with its exit-code contract, its cost, when to run
237
+ SHARED CLI call this lane makes, each with its exit-code contract, its cost, when to run
238
238
  it, and what an EMPTY answer means. Never invent a spelling, never re-word an
239
239
  exit code, and never re-derive a state word — the CLI's state words are the only
240
240
  state words, and **an exit code is an ANSWER wherever that contract says so, not
241
- a failure**. A call the answer does not name is a call this lane does not make.
241
+ a failure**. A call that neither it nor this skill names is a call this lane does not make.
242
242
  Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
243
- command you are about to run, out loud, before running it.
244
-
245
- ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
246
-
247
- `orc rules slice --lane orc-budget --json` is the ONLY assembler; never build
248
- the card here. It rides under the house rules and above the task —
249
- **house rules > your project's rules > ORC's own packs** — and its `line` prints
250
- VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
251
- never a silent choice) and `rules_overridden[]`.
252
- ## Waiting mid-run (`/orc-wait`)
253
-
254
- Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
255
- Checkpoint **none** · safe point **read-only, seconds long**. 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.
243
+ command you are about to run, out loud, before running it.
244
+
245
+ ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
246
+
247
+ `orc rules slice --lane orc-budget --json` is the ONLY assembler; never build
248
+ the card here. It rides under the house rules and above the task —
249
+ **house rules > your project's rules > ORC's own packs** — and its `line` prints
250
+ VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
251
+ never a silent choice) and `rules_overridden[]`.
252
+ ## Waiting mid-run (`/orc-wait`)
253
+
254
+ Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
255
+ Checkpoint **none** · safe point **read-only, seconds long**. 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.
@@ -135,7 +135,7 @@ one.
135
135
 
136
136
  ## Reading order for a new maintainer
137
137
 
138
- `../_shared/phases/intake.md` (it defines what every later file grades against) →
138
+ `references/intake.md` (it defines what every later file grades against) →
139
139
  `council.md` → `sealed-slice.md` → `rubric.md` → `conservation.md` →
140
140
  `cycle-state.md` → `fix-brief.md`. Then `examples/tsd-two-iterations.md` for the
141
141
  whole thing end to end, and `examples/council-full-roster.md` for a run where
@@ -115,7 +115,7 @@ themselves are this lane's own and stay here.
115
115
  ## C1 — Intake (ONE round, ASK — never guess)
116
116
 
117
117
  Full field list, the round format and the "I don't know yet" exit:
118
- `../_shared/phases/intake.md`. It ends by running `orc challenge init`, which **freezes
118
+ `references/intake.md`. It ends by running `orc challenge init`, which **freezes
119
119
  `goals.md`, `template.md` and the COUNCIL ROSTER**.
120
120
 
121
121
  **Question 7 is the P0 council ask**, rendered from `orc challenge roles --kind
@@ -284,22 +284,22 @@ documented defaults, out loud. Priorities and families:
284
284
  ## Calls
285
285
 
286
286
  **ONE catalogue, and it is not you:** `orc lane calls orc-challenge --json` names every
287
- CLI call this lane makes, each with its exit-code contract, its cost, when to run
287
+ SHARED CLI call this lane makes, each with its exit-code contract, its cost, when to run
288
288
  it, and what an EMPTY answer means. Never invent a spelling, never re-word an
289
289
  exit code, and never re-derive a state word — the CLI's state words are the only
290
290
  state words, and **an exit code is an ANSWER wherever that contract says so, not
291
- a failure**. A call the answer does not name is a call this lane does not make.
291
+ a failure**. A call that neither it nor this skill names is a call this lane does not make.
292
292
  Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
293
- command you are about to run, out loud, before running it.
294
-
295
- ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
296
-
297
- `orc rules slice --lane orc-challenge --json` is the ONLY assembler; never build
298
- the card here. It rides under the house rules and above the task —
299
- **house rules > your project's rules > ORC's own packs** — and its `line` prints
300
- VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
301
- never a silent choice) and `rules_overridden[]`.
302
- ## Waiting mid-run (`/orc-wait`)
303
-
304
- Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
305
- Checkpoint **cycle** · safe point **after a cycle records**. `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.
293
+ command you are about to run, out loud, before running it.
294
+
295
+ ## Rules — the anti-slop card (`../_shared/phases/rules.md`)
296
+
297
+ `orc rules slice --lane orc-challenge --json` is the ONLY assembler; never build
298
+ the card here. It rides under the house rules and above the task —
299
+ **house rules > your project's rules > ORC's own packs** — and its `line` prints
300
+ VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
301
+ never a silent choice) and `rules_overridden[]`.
302
+ ## Waiting mid-run (`/orc-wait`)
303
+
304
+ Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
305
+ Checkpoint **cycle** · safe point **after a cycle records**. `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.
@@ -15,7 +15,7 @@ for a PRD includes the two lenses that never block.
15
15
  > /orc-challenge docs/prd-self-serve.md
16
16
  ```
17
17
 
18
- The first six questions are unchanged (`../../_shared/phases/intake.md`). Question 7 is
18
+ The first six questions are unchanged (`references/intake.md`). Question 7 is
19
19
  rendered from `orc challenge roles --kind prd --json` — **the skill never
20
20
  hand-lists the lenses**:
21
21
 
@@ -74,7 +74,7 @@ set in "Behavior trace").
74
74
  does not change this role) with: `mode`, `repo_root`,
75
75
  `budget` (from a `budget=N` argument, else null), and the paths to
76
76
  `references/template.md` + `references/refresh.md`. **Trace:** emit
77
- `DISPATCH orc-claude-writer :: <mode> expect=opus-5/low` just before the
77
+ `DISPATCH orc-claude-writer :: <mode> expect=opus-5-5/low` just before the
78
78
  spawn (the expectation is derived from the agent NAME you actually
79
79
  dispatched, never from this line's default; the hook then adds
80
80
  `SPAWN`/`RETURN` on its own).
@@ -175,7 +175,7 @@ Dispatch-only lane: emit ONLY the markers it can truthfully witness — **not**
175
175
  `PHASE`/`SCORE`/`FINDING`/`VERDICT`, because scan/generate/report run INSIDE
176
176
  the writer sub-agent and there is no scoring or review here. The marker set, in
177
177
  order (actor `orc`, plus the hook's `SPAWN`/`RETURN`): `DISPATCH
178
- orc-claude-writer :: <mode> expect=opus-5/low` before the spawn (the mode
178
+ orc-claude-writer :: <mode> expect=opus-5-5/low` before the spawn (the mode
179
179
  rides in this tail and in `FINISH`, so no separate mode marker) · `VERIFY writer
180
180
  actual=<model>/<effort>` · `FINISH :: <mode_ran> CLAUDE.md v<X.Y.Z>`, where
181
181
  `mode_ran` may be `noop`. A noop refresh still traces the full cycle.
@@ -207,11 +207,11 @@ documented defaults, out loud. Priorities and families:
207
207
  ## Calls
208
208
 
209
209
  **ONE catalogue, and it is not you:** `orc lane calls orc-claude --json` names every
210
- CLI call this lane makes, each with its exit-code contract, its cost, when to run
210
+ SHARED CLI call this lane makes, each with its exit-code contract, its cost, when to run
211
211
  it, and what an EMPTY answer means. Never invent a spelling, never re-word an
212
212
  exit code, and never re-derive a state word — the CLI's state words are the only
213
213
  state words, and **an exit code is an ANSWER wherever that contract says so, not
214
- a failure**. A call the answer does not name is a call this lane does not make.
214
+ a failure**. A call that neither it nor this skill names is a call this lane does not make.
215
215
  Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
216
216
  command you are about to run, out loud, before running it.
217
217
 
@@ -50,7 +50,7 @@ dispatches the trace writer ONCE at run end to append them (`SPAWN`/`RETURN`
50
50
  come from the `orc-trace.js` hook as they occur):
51
51
 
52
52
  ```
53
- [120726 09:14:02.110] writer DISPATCH orc-claude-writer :: refresh expect=opus-5/low
53
+ [120726 09:14:02.110] writer DISPATCH orc-claude-writer :: refresh expect=opus-5-5/low
54
54
  [120726 09:14:02.230] hook SPAWN orc-claude-writer-opus-5-low
55
55
  [120726 09:15:47.900] hook RETURN
56
56
  [120726 09:15:48.010] writer VERIFY writer actual=claude-opus-5-5/low ✅ MATCH
@@ -60,8 +60,8 @@ SKILL.md as a spine — the flow names every subskill and schema it needs.
60
60
 
61
61
  ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
62
62
 
63
- - **Calls:** `orc lane calls orc-diy --json` names every call and its exit codes.
64
- **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
63
+ - **Calls:** `orc lane calls orc-diy --json` names shared calls and exit codes.
64
+ **An exit code is an ANSWER where it says so, not a failure.** Own calls are here; make no other.
65
65
  - **Config:** `orc lane config orc-diy --json`. Obey `effective`, print every line
66
66
  in `announce[]` VERBATIM at preflight, and honour `stops[]` before wave 1.
67
67
  Never merge `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).