@orkestrel/scaffold 0.0.71 → 0.0.72

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 (60) hide show
  1. package/dist/host/CLAUDE.md +3 -3
  2. package/dist/host/agents/orchestration.md +66 -32
  3. package/dist/host/agents/skills/enterprise-bootstrap/references/bootstrap-reference.md +36 -6
  4. package/dist/host/agents/skills/enterprise-bootstrap/references/color-modes.md +3 -2
  5. package/dist/host/agents/skills/enterprise-bootstrap/references/components.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-build-application/SKILL.md +18 -1
  7. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +2 -4
  9. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +12 -9
  10. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +16 -8
  11. package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +2 -2
  12. package/dist/host/agents/skills/orkestrel-harden-package/SKILL.md +1 -1
  13. package/dist/host/agents/skills/orkestrel-polish-surface/SKILL.md +2 -1
  14. package/dist/host/agents/skills/orkestrel-prove-journey/SKILL.md +19 -8
  15. package/dist/host/agents/skills/orkestrel-prove-journey/references/layer.md +16 -15
  16. package/dist/host/agents/skills/orkestrel-prove-journey/references/statechart.md +5 -2
  17. package/dist/host/agents/skills/orkestrel-prove-journey/references/styles.md +5 -1
  18. package/dist/host/agents/templates/brief.md +4 -3
  19. package/dist/host/agents/transports/claude.md +13 -6
  20. package/dist/host/agents/transports/codex.md +2 -2
  21. package/dist/host/agents/transports/cursor.md +85 -0
  22. package/dist/host/claude/agents/application.md +5 -6
  23. package/dist/host/claude/agents/builder.md +3 -13
  24. package/dist/host/claude/agents/checker.md +9 -2
  25. package/dist/host/claude/agents/distiller.md +37 -0
  26. package/dist/host/claude/agents/grok.md +9 -56
  27. package/dist/host/claude/agents/{implementer.md → opus.md} +8 -9
  28. package/dist/host/claude/agents/orkestrel.md +7 -0
  29. package/dist/host/claude/agents/planner.md +12 -5
  30. package/dist/host/claude/agents/researcher.md +7 -0
  31. package/dist/host/claude/agents/reviewer.md +14 -7
  32. package/dist/host/claude/agents/scout.md +8 -1
  33. package/dist/host/claude/agents/sol.md +5 -5
  34. package/dist/host/claude/rules/documentation.md +1 -0
  35. package/dist/host/claude/rules/writing.md +27 -24
  36. package/dist/host/claude/skills/orkestrel-build-application/SKILL.md +1 -1
  37. package/dist/host/codex/agents/analyst.toml +10 -4
  38. package/dist/host/codex/agents/application.toml +5 -6
  39. package/dist/host/codex/agents/builder.toml +5 -5
  40. package/dist/host/codex/agents/checker.toml +4 -0
  41. package/dist/host/codex/agents/distiller.toml +28 -0
  42. package/dist/host/codex/agents/grok.toml +27 -19
  43. package/dist/host/codex/agents/opus.toml +5 -4
  44. package/dist/host/codex/agents/orkestrel.toml +5 -0
  45. package/dist/host/codex/agents/planner.toml +10 -0
  46. package/dist/host/codex/agents/researcher.toml +4 -0
  47. package/dist/host/codex/agents/reviewer.toml +12 -2
  48. package/dist/host/codex/agents/scout.toml +5 -2
  49. package/dist/host/codex/agents/{implementer.toml → sol.toml} +5 -6
  50. package/dist/host/codex/agents/verifier.toml +3 -0
  51. package/dist/host/codex/config.toml +2 -2
  52. package/dist/host/configs/policy.ts +5 -2
  53. package/dist/host/manifest.json +74 -56
  54. package/dist/src/core/index.cjs +448 -349
  55. package/dist/src/core/index.cjs.map +1 -1
  56. package/dist/src/core/index.d.cts +22 -21
  57. package/dist/src/core/index.d.ts +22 -21
  58. package/dist/src/core/index.js +448 -349
  59. package/dist/src/core/index.js.map +1 -1
  60. package/package.json +4 -4
@@ -27,9 +27,9 @@ follows it. This file adds only what Claude Code does differently, and cannot we
27
27
  - Run the main session on `opus` at high effort, set by `/model opus` or `"model": "opus"`. Opus 5
28
28
  is the Orchestrator in this harness. Its Orchestrator duties are unchanged if it is configured
29
29
  otherwise.
30
- - The Orchestrator shares its engine with `planner`, `reviewer`, and the Opus `implementer`. Run
31
- the Sol `analyst` in every design round and every audit round so the judgment is not single-engine,
32
- and confirm from its journal that it reached Sol. A bridge driver that answers from its own engine
30
+ - The Orchestrator shares its engine with `planner`, `reviewer`, and `opus`. Run the Sol `analyst`
31
+ in every design round and every audit round so the judgment is not single-engine, and confirm from
32
+ its journal that it reached Sol. A bridge driver that answers from its own engine
33
33
  collapses the round to one engine and its ruling still reads as normal.
34
34
  - Claude role frontmatter accepts Claude models only. Reach Grok through `grok`, and Sol through
35
35
  `analyst` and `sol`. Never put an external model in `model:`. Treat
@@ -86,6 +86,13 @@ names nothing else, so never write it of a lane. A verdict file's recorded reaso
86
86
 
87
87
  By default Opus 5 holds the subjective lane and Sol holds the objective lane.
88
88
 
89
+ Swap the lanes whenever the round needs an engine that is not the one running that lane. Bench
90
+ darkness is one trigger and the writer's engine is another: § Execution loop's audit step requires
91
+ an auditor that did not write the work, so where Sol wrote the work under audit, give the objective
92
+ lane to Opus 5 and the subjective lane to Sol, and reverse that where Opus 5 wrote it. Both engines
93
+ still run, so this is a lane swap rather than a substitution. Record which engine held which lane in
94
+ the routing ledger.
95
+
89
96
  When one engine is unavailable, the remaining engine runs **every** lane — still separate
90
97
  subagents, still clean contexts, still blind to each other, each told which perspective it holds.
91
98
  Record the substitution.
@@ -121,6 +128,9 @@ Fall back in this order and record the substitution:
121
128
  2. **Luna** (`gpt-5.6-luna`), when the Cursor bench is dark and Codex is available.
122
129
  3. **Sonnet**, when both benches are dark.
123
130
 
131
+ - Dispatch `distiller` for absorption and distillation after the ladder steps past Grok, and
132
+ `researcher`, `scout`, or `checker` for the job each of those names. `scout` excludes deep
133
+ reading and `researcher` excludes repository-scale absorption, so neither takes that step.
124
134
  - Never route absorption to the Orchestrator itself, even when the Orchestrator is Grok. Keep the
125
135
  main context at decision level; in Cursor that means a Grok executor session, not this one.
126
136
  - Never spend Opus 5 or Sol on it.
@@ -155,8 +165,9 @@ when the role file already pins it.
155
165
  | Creative design and alternatives | `planner` | `planner` | Opus 5 (native / bridge) |
156
166
  | Design-fit review and audit | `reviewer` | `reviewer` | Opus 5 (native / bridge) |
157
167
  | Objective analysis and correctness audit | `analyst` | `analyst` | GPT-5.6 Sol (bridge / native) |
158
- | Nontrivial implementation (objective) | `sol` | `implementer` | GPT-5.6 Sol (bridge / native) |
159
- | Nontrivial implementation (subjective) | `implementer` | `opus` | Opus 5 (native / bridge) |
168
+ | Nontrivial implementation (objective) | `sol` | `sol` | GPT-5.6 Sol (bridge / native) |
169
+ | Nontrivial implementation (subjective) | `opus` | `opus` | Opus 5 (native / bridge) |
170
+ | Bulk reading and evidence distillation | `distiller` | `distiller` | Grok → Luna → Sonnet |
160
171
  | Bounded primary-source research | `researcher` | `researcher` | Grok → Luna → Sonnet |
161
172
  | Repository reconnaissance | `scout` | `scout` | Grok → Luna → Sonnet |
162
173
  | Mechanical conformance evidence | `checker` | `checker` | Grok → Luna → Sonnet |
@@ -167,9 +178,11 @@ when the role file already pins it.
167
178
 
168
179
  - A **bridge** role is a cheap driver whose only work is invoking another provider's CLI. It never
169
180
  implements, judges, or endorses the result.
170
- - `implementer` names the harness's native implementation lane, so the token means Opus in Claude
171
- Code and Sol in Codex. An engine-named bridge — `sol`, `opus` — names the other engine. Read a
172
- role name against the harness you are running in, and state the engine anyway.
181
+ - `sol` and `opus` each name one engine on both provider surfaces. The harness decides whether the
182
+ role is native or a bridge; the name never does. State the engine in the dispatch anyway.
183
+ - A role name and a model alias occupy different fields — a dispatch and a role file's `name` carry
184
+ the role, a `model:` pin carries the alias — so the Codex `opus` bridge is a role named `opus`
185
+ pinned to the `gpt-5.6-terra` model.
173
186
  - Give every role a file in the scaffold checkout, under `.claude/agents/` and under
174
187
  `.codex/agents/`. The role file is where engine, effort, tools, permissions, and charter are
175
188
  pinned, and the tool allowlist is what makes the read-only floor real. A role with no file has
@@ -177,9 +190,9 @@ when the role file already pins it.
177
190
  catalog agent and no other role, and a session that dispatches roles starts on scaffold and
178
191
  attaches the target.
179
192
  - Reach every role by its own name. Do not rely on a remembered route.
180
- - `researcher`, `scout`, and `checker` are native lanes for jobs that belong to Grok first.
181
- Dispatch `grok` with their brief before using them, and use the native role only once the ladder
182
- has stepped past Grok. Record which step you are on.
193
+ - `distiller`, `researcher`, `scout`, and `checker` are native lanes for jobs that belong to Grok
194
+ first. Dispatch `grok` with their brief before using them, and use the native role only after the
195
+ ladder has stepped past Grok. Record which step you are on.
183
196
  - `orkestrel` stays native because it carries the package catalog in its own role file. Sending its
184
197
  job to a bench means shipping that catalog across, which costs more than the bench saves.
185
198
  - A transport contract lives in `.agents/transports/`, not in an agents directory. A harness lists
@@ -188,9 +201,13 @@ when the role file already pins it.
188
201
  `.agents/transports/claude.md` the shared Opus transport contract. Neither is a route: `analyst`
189
202
  and `sol` are the named Sol bridges, `planner`, `reviewer`, and `opus` the named Opus bridges, and
190
203
  each binds its own contract by reference and pins only its route and sandbox.
204
+ `.agents/transports/cursor.md` is the shared Cursor transport contract, and both harnesses' `grok`
205
+ bridges bind it, because Cursor is native to neither. A contract's home is the provider it carries,
206
+ never the harness that reaches it.
191
207
  - Mirroring is by work class, not filename. A transport contract is provider-specific: the Codex
192
208
  contract carries the Sol transport the Claude-side bridges follow, the Claude contract carries the
193
- Opus transport the Codex-side bridges follow, and each side's bridges bind their own.
209
+ Opus transport the Codex-side bridges follow, and each bridge binds the contract of the provider it
210
+ reaches.
194
211
  - Opus and Sol roles use high effort. Native cheap-tier roles use low or medium. Bridge drivers use
195
212
  the cheapest tier that can run a CLI.
196
213
  - Never route orchestration or acceptance across a bridge.
@@ -333,10 +350,10 @@ longer holds.
333
350
  - State the goal's exit criterion beside the units: the enumerated capabilities whose closure
334
351
  ends the campaign, each to end implemented, repaired, retained, or intentionally excluded on
335
352
  evidence. A plan that names work but not its end can only be abandoned, never finished.
336
- 3. **Implement.** Route each nontrivial objective unit to the Sol `implementer` and each nontrivial
337
- subjective unit to the Opus `implementer`, in the checkout the unit writes, one writer per
338
- checkout. Route a fully specified taste-free unit to `builder`. Never route implementation to an
339
- engine the unit's judgment load exceeds.
353
+ 3. **Implement.** Route each nontrivial objective unit to `sol` and each nontrivial subjective unit
354
+ to `opus`, in the checkout the unit writes, one writer per checkout. Route a fully specified
355
+ taste-free unit to `builder`. Never route implementation to an engine the unit's judgment load
356
+ exceeds.
340
357
  4. **Integrate.** Evaluate each distillate against its acceptance criteria, apply shared-file
341
358
  patches serially, and route cross-cutting findings. Integration applies exact returned patches
342
359
  and mechanical conflict resolution only. A new type, mechanism, behavior, or acceptance
@@ -388,9 +405,15 @@ that needs the user.
388
405
 
389
406
  ## Deviation protocol
390
407
 
391
- When reality diverges from a writing dispatch:
408
+ Stop when a conflict prevents the primary objective or requires an unowned change. Resolve an
409
+ ancillary choice within the owned scope, record the choice, and continue.
410
+
411
+ Every charter references this section rather than restating it. A charter keeps only a stop
412
+ condition its own route owns, such as a misrouted unit it must refuse.
413
+
414
+ When a writer stops:
392
415
 
393
- 1. The writer stops and reports: expected, found, exact evidence, done or not done, and at most one
416
+ 1. The writer reports: expected, found, exact evidence, done or not done, and at most one
394
417
  short hypothesis. It does not investigate, improvise, or alter the plan.
395
418
  2. The Orchestrator triages:
396
419
  - obvious correction → tighten and re-dispatch;
@@ -432,12 +455,16 @@ The harness bridge names the concrete mechanism for each of these.
432
455
  unit's instruction and its outcome are one pair on disk.
433
456
  - Name, inside a report that rests on a bench lane, that lane's journal path and session id, so
434
457
  the provenance survives the journal's sweep.
435
- - Amend a brief on re-run rather than restating it. A mid-campaign correction produces a successor
436
- file recording what changed and why, and the original stays. A fix round's brief names the
437
- findings it carries and where each came from.
458
+ - Re-run a unit with a successor brief, never with an edit to the brief it already ran. Name the
459
+ successor `<unit>-brief-<n>.md`, state in it what changed and why, and leave the original in place
460
+ unedited. A fix round's brief names the findings it carries and where each came from.
438
461
  - Name a corrected unit's effective brief and report and the pair they supersede before that unit
439
462
  integrates. A unit whose correction landed as a serial patch or a direct reconciliation, with no
440
463
  successor pair on disk, cannot be re-run from what the campaign kept.
464
+ - Write an audit round's numbered claims to `tmp/audit/<unit>-audit-claims.md` and point every lane
465
+ of the round at that one file, so "both lanes ran the same brief" stays checkable after the round.
466
+ Retain it as `.orkestrel/<package>/<unit>-audit-claims.md`, beside the round's verdict.
467
+ `.agents/skills/orkestrel-falsify/references/brief.md` owns what the claims say.
441
468
  - Write the round's verdict to `.orkestrel/<package>/<unit>-audit-verdict.md`. That file is where
442
469
  the audit step records a lane or a checker that did not run.
443
470
  - Read the copy the executor will open, not the one you wrote. A brief written in the orchestrator's
@@ -446,6 +473,8 @@ The harness bridge names the concrete mechanism for each of these.
446
473
  staged copy whose facts are false stops a unit that was correctly briefed. Verify the staged path
447
474
  and its load-bearing facts before launching, and stage into a scratch directory the subject tree
448
475
  ignores rather than into the checkout root.
476
+ - Before dispatching a successor or accepting a round, open every file the effective brief names
477
+ and confirm it resolves from the executor's root. Refuse the transition when one does not.
449
478
  - Send a decision taken mid-campaign to every unit already in flight whose brief it invalidates. An
450
479
  executor cannot see a change made after it was dispatched, so it writes the state its brief
451
480
  described and the defect surfaces as its own.
@@ -453,10 +482,14 @@ The harness bridge names the concrete mechanism for each of these.
453
482
  integration, fix, probe, or capture unit: copy the brief, the returned report or distillate, the
454
483
  audit verdict, the exact executed script or instrument, and the acceptance evidence into
455
484
  `.orkestrel/<package>/` as the unit is dispatched and as it returns, then sweep only the `tmp/`
456
- launch copies. A capture claim's instrument is acceptance evidence; the frames may be swept once
457
- the record transcribes them, because the committed instrument re-produces the film. The **Bench
458
- laws** rule "Ephemeral streams, durable records" owns journals and points here for everything
459
- durable.
485
+ launch copies. Rewrite every `tmp/` path inside a copied artifact to the retained path it now
486
+ names, in the same action that copies it. A retained file naming a launch copy resolves to
487
+ nothing after the sweep, and the successor, the claim list, and the staged authority always do.
488
+ Retention covers every lane of an audit round, including the lane whose brief produced a
489
+ deviation: a round with a retained report and no retained brief cannot be re-run. A capture
490
+ claim's instrument is acceptance evidence; the frames may be swept once the record transcribes
491
+ them, because the committed instrument re-produces the film. The **Bench laws** rule "Ephemeral
492
+ streams, durable records" owns journals and points here for everything durable.
460
493
  - Name a retained log with the `<unit>.log.txt` pattern, never with a bare `.log` suffix, which the
461
494
  root `.gitignore` file ignores.
462
495
  - Promote anything that must outlive the campaign into a durable artifact before the sweep — a
@@ -519,10 +552,9 @@ The harness bridge names the concrete mechanism for each of these.
519
552
  with **Bench laws** rule "Journal first" and refuse a bench result whose journal path and session
520
553
  id are absent.
521
554
  - **Output.** The exact distilled return shape. No process diary.
522
- - **Deviation contract.** The required stop-and-report behaviour for writers, scoped. A conflict
523
- with the primary objective stops the unit. An ancillary conflict — where a paragraph sits, which
524
- heading a section takes — is the executor's to decide, record, and carry on from. An unscoped
525
- contract stops a unit over a detail it was equipped to settle.
555
+ - **Deviation contract.** Point the writer at § Deviation protocol and scope it: name the ancillary
556
+ choices this unit settles itself — where a paragraph sits, which heading a section takes. An
557
+ unscoped contract stops a unit over a detail it was equipped to settle.
526
558
  - **Acceptance criteria.** Independently checkable completion conditions.
527
559
  - **Review evidence.** What the subject type requires, per the table in `orkestrel-falsify`. For a
528
560
  code change that is the actual diff and the actual status output; omitting either is a dispatch
@@ -533,8 +565,10 @@ The harness bridge names the concrete mechanism for each of these.
533
565
 
534
566
  ### Check the brief before you send it
535
567
 
536
- Fill `.agents/templates/brief.md`, which carries the named scope rows and the worked reason behind
537
- each check. Then run this checklist against what you filled.
568
+ Fill `.agents/templates/brief.md`, keeping its section and row headings verbatim, so a row you
569
+ cannot close is visible as a heading with a named unknown under it rather than as an absence nobody
570
+ can see. Add a section the unit needs; never drop one. Then run this checklist against what you
571
+ filled.
538
572
 
539
573
  - Name the executor that will open the brief, and write the transport for that reader. A bridge
540
574
  driver and the bench engine inside that driver's CLI need opposite instructions.
@@ -629,9 +663,9 @@ command that outlives the turn that started it. Every law here binds all of them
629
663
  launch whose tail is the evidence.
630
664
  - Keep network-dependent work out of sandboxed bench execs. Bench sandboxes deny network, so
631
665
  lockfile generation, real installs, and live fetches belong to the Orchestrator's own tracked
632
- commands or to the native `implementer` or `builder` as an ordinary dispatched writing unit. A
633
- bench exec hanging on `npm` until its cap fires is the signature of this misroute, not of a slow
634
- bench.
666
+ commands or to whichever of `sol`, `opus`, and `builder` runs natively in the harness, as an
667
+ ordinary dispatched writing unit. A bench exec hanging on `npm` until its cap fires is the
668
+ signature of this misroute, not of a slow bench.
635
669
  - A Workflow journals identically and dies identically, so give it the same watch — with one
636
670
  correction. A workflow journal writes only at agent start and result, so its mtime goes quiet for
637
671
  minutes during healthy work, and the liveness signal is the newest subagent transcript instead. A
@@ -743,7 +777,7 @@ transport.
743
777
  child. It fails as a **false green**. The stage never arms, the boot inspection times out, and that
744
778
  timeout produces the same rejection a genuine stage timeout produces, so a test asserting on the
745
779
  message passes inside the bench while the host's gate reports the honest red — and neither run
746
- reports why they disagree. Route such a subject to the harness's native implementer, or keep it on
780
+ reports why they disagree. Route such a subject to the harness's native writing lane, or keep it on
747
781
  the bench and supply every executed measurement yourself. Never dispatch it to a bench and expect
748
782
  it to prove its own work. The shape to recognise is a child that exits 0 almost immediately, a
749
783
  request to it that never resolves, and a stack landing in the spawning code's exit handler.
@@ -14,7 +14,7 @@
14
14
  - [Forms in production](#forms-in-production)
15
15
  - [JavaScript lifecycle](#javascript-lifecycle)
16
16
  - [Accessibility](#accessibility)
17
- - [Enterprise patterns](#enterprise-patterns) — [App shell](#app-shell) · [Dense data tables](#dense-data-tables) · [Filter & search bars](#filter--search-bars) · [Wizards & multi-step forms](#wizards--multi-step-forms) · [The data states](#the-data-states) · [Feedback discipline](#feedback-discipline) · [Destructive actions](#destructive-actions)
17
+ - [Enterprise patterns](#enterprise-patterns) — [App shell](#app-shell) · [Dense data tables](#dense-data-tables) · [Filter & search bars](#filter--search-bars) · [Wizards & multi-step forms](#wizards--multi-step-forms) · [The data states](#the-data-states) · [Refused capabilities](#refused-capabilities) · [Feedback discipline](#feedback-discipline) · [Destructive actions](#destructive-actions)
18
18
  - [RTL](#rtl)
19
19
  - [Print](#print)
20
20
  - [Performance](#performance)
@@ -114,9 +114,10 @@ measured role that requires it. Do not turn every subtle panel into a custom col
114
114
 
115
115
  ### Theme toggle
116
116
 
117
- Reuse the host controller. When implementing one, follow [Scope the mode](color-modes.md#scope-the-mode)
118
- for validated preference, automatic-mode resolution, storage failure, first paint, and overlay
119
- mounts. Bootstrap ships no picker; an attribute example is not a complete controller.
117
+ Reuse the host controller. When implementing one, follow
118
+ [Scope the mode](color-modes.md#scope-the-mode) for validated preference, automatic-mode resolution,
119
+ first paint, and overlay mounts, and [Refused capabilities](#refused-capabilities) for a refused read
120
+ or write. Bootstrap ships no picker; an attribute example is not a complete controller.
120
121
 
121
122
  ### Custom modes
122
123
 
@@ -484,7 +485,7 @@ Client-side, the documented pattern:
484
485
  </script>
485
486
  ```
486
487
 
487
- **Documented limitation (enterprise-critical):** Bootstrap's client-side validation styles and `valid/invalid-tooltip`s are **not exposed to assistive technologies**. For accessible flows use the server-side pattern — apply `.is-invalid` / `.is-valid` directly (no `.was-validated` parent needed), with `.invalid-feedback` linked through `aria-describedby` — or rely on native browser validation.
488
+ **Documented limitation:** Bootstrap's client-side validation styles and `valid/invalid-tooltip`s are **not exposed to assistive technologies**. For accessible flows use the server-side pattern — apply `.is-invalid` / `.is-valid` directly (no `.was-validated` parent needed), with `.invalid-feedback` linked through `aria-describedby` — or rely on native browser validation.
488
489
 
489
490
  ```html
490
491
  <input
@@ -573,7 +574,12 @@ Wire the reader into the suite after it has settled a question.
573
574
 
574
575
  ### WCAG 2.2 requirements for app UI
575
576
 
576
- - **Target size (2.5.8, AA) — this section owns the skill's target dimensions.** Hold every applicable target at ≥ 24×24 CSS px: icon buttons, row actions, close buttons, sort carets, checkbox hit-areas, and color swatches. A smaller visual target passes only where a 24px spacing circle around it stays undisturbed — so in tight `table-sm` toolbars, pad the hit area rather than enlarging the glyph. Prefer 44×44 CSS px for a primary mobile control. Measure the rendered hit area; never infer it from a size class such as `btn-sm`. Enlarge the button or its associated label, not the icon's surrounding decoration.
577
+ - **Target size (2.5.8, AA) — this section owns the skill's target dimensions.** Hold every applicable target at ≥ 24×24 CSS px: icon buttons, row actions, close buttons, sort carets, checkbox hit-areas, and color swatches. A smaller visual target passes only where a 24px spacing circle around it stays undisturbed — so in tight `table-sm` toolbars, pad the hit area rather than enlarging the glyph. Prefer 44×44 CSS px for a primary mobile control. Measure the rendered hit area; never infer it from a size class such as `btn-sm`. Enlarge the button or its associated label, not the icon's surrounding decoration. An inline target whose text can wrap paints one rectangle per line, and the rectangles are disjoint,
578
+ so the centre of its bounding box can land between them and resolve to the ancestor. Make such a
579
+ target `d-block`, `d-grid`, or a `stretched-link` container wherever a click must land anywhere in
580
+ its box. Never enlarge one through `line-height`, which widens the gap between the rectangles rather
581
+ than the rectangles. Measure the hit area at the narrowest supported viewport, where the target
582
+ wraps, not only where it fits one line.
577
583
  - **Focus not obscured (2.4.11, AA).** Sticky headers/footers/action bars and toast overlays must not bury the focused element. Reserve space with `scroll-margin-top` on focusables (or `scroll-padding-top` on the scroll container) equal to the sticky chrome height.
578
584
  - **Dragging alternatives (2.5.7, AA).** Any drag (row reorder, kanban, slider, resize) needs a non-drag single-pointer path: move up/down buttons, numeric input, click-to-place.
579
585
  - **Accessible authentication (3.3.8, AA).** Never block paste in password/OTP fields; support password managers; no puzzle as the only way in.
@@ -762,6 +768,30 @@ Design **every one** for every data surface: ideal (populated), empty, loading,
762
768
  to it. Missing is not zero. Do not collapse the whole surface into an error when some data exists.
763
769
  - **Every error state states what failed and how to fix it**, carries a keyboard-reachable retry in place, and preserves surrounding context — a body fetch failure must not blow away the toolbar and filters.
764
770
 
771
+ ### Refused capabilities
772
+
773
+ A browser capability the document asks for can refuse at the call site. A storage write raises
774
+ `QuotaExceededError` when no room is left, and a storage read raises when the browser holds that
775
+ capability behind a permission. Give a refusal the treatment [The data states](#the-data-states)
776
+ requires of every other state.
777
+
778
+ - **Paint before you persist.** Apply the state to the document first, then write it. A control
779
+ deriving its label and `aria-pressed` from a flag the write moves announces a state the document
780
+ is not in as soon as the write refuses.
781
+ - **Catch at the boundary that makes the call**, not at the caller. A read that runs during
782
+ construction takes the whole surface down when it escapes, and the person gets a blank page
783
+ instead of a degraded one.
784
+ - **Default a refused read to the state a first-time reader gets.** The person who cleared site data
785
+ and the person whose browser refuses the read arrive at the same screen.
786
+ - **Keep the action working for this session.** The refusal costs the memory of the preference.
787
+ Never let it also cost the behavior the person asked for.
788
+ - **Say nothing about a refusal the person does not experience.** A preference that paints and does
789
+ not survive the session earns no failure sentence and no retry control: the action succeeded, and
790
+ a retry writes the same value to the same refusing store. Where the refusal does cost the person
791
+ something they asked for, carry it on the channel [Feedback discipline](#feedback-discipline)
792
+ names for its scope — inline alert for a refusal tied to one control, banner for a capability the
793
+ whole surface needs.
794
+
765
795
  ### Feedback discipline
766
796
 
767
797
  | Channel | Use for | Never for |
@@ -257,8 +257,9 @@ then inherited into a different local mode. Consume the Bootstrap variable at th
257
257
  rebind the alias at every supported mode boundary. Custom properties resolve their references
258
258
  before inheritance; see [CSS Custom Properties](https://www.w3.org/TR/css-variables-1/).
259
259
 
260
- When implementing a picker, validate persisted values, tolerate unavailable storage, and resolve
261
- `auto` through `prefers-color-scheme` before setting the attribute. Follow system changes only
260
+ When implementing a picker, validate persisted values and resolve `auto` through
261
+ `prefers-color-scheme` before setting the attribute. Take a refused read or write from
262
+ [bootstrap-reference.md](bootstrap-reference.md) → Refused capabilities. Follow system changes only
262
263
  while the preference is automatic. Apply the resolved mode before first paint, keep server/client
263
264
  initial state consistent, and update the picker's accessible state. Do not write
264
265
  `data-bs-theme="auto"` without an explicitly implemented custom mode. Take the integration details
@@ -995,7 +995,7 @@ const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]
995
995
  const popoverList = [...popoverTriggerList].map((el) => new bootstrap.Popover(el))
996
996
 
997
997
  // Programmatic control — prefer getOrCreateInstance over `new` when the
998
- // element may already be initialized (e.g. by a data attribute)
998
+ // element may already be initialized (for example, by a data attribute)
999
999
  const myModal = bootstrap.Modal.getOrCreateInstance('#myModal')
1000
1000
  myModal.show()
1001
1001
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: orkestrel-build-application
3
- description: Design, scaffold, extend, or harden Orkestrel `app/core`, `app/browser`, and `app/server` environments. Use for app-only or mixed src/app workspaces, app environment isolation, Vue browser entries, Node server entries, app aliases/configs/scripts/tests, cross-environment contracts, and application guide parity.
3
+ description: Wire, extend, or harden Orkestrel `app/core`, `app/browser`, and `app/server` environments — the environment's contracts, boundaries, entries, and host proofs, never the product designed inside one. Use for app-only or mixed src/app workspaces, app environment isolation, Vue browser entries, Node server entries, app aliases, configs, scripts, and tests, cross-environment contracts, and application guide parity. Do not use it to redesign an application's routes, screens, or domain behavior; take that to a design round and return here to wire what it decides.
4
4
  ---
5
5
 
6
6
  # Build an Orkestrel application
@@ -106,3 +106,20 @@ includes app/core so the shared transport contracts have one host-independent ow
106
106
  Do not add showcase, authentication, persistence, proxy, styling-system, or product
107
107
  policy unless the request requires it. Do not leave placeholders, compatibility shims,
108
108
  empty setup files, or deferred app behavior.
109
+
110
+ ## Accept the result
111
+
112
+ Completion requires:
113
+
114
+ - every selected environment's `types.ts` implemented and mirrored in tests;
115
+ - every boundary-enforcement layer in step 6 reporting clean over the selected environments;
116
+ - the step 7 real-host proofs run and recorded with their counts — real DOM under
117
+ Playwright-backed Vitest Browser Mode, loopback port zero under real fetch, and
118
+ executable readiness, collision exit, signal termination, and port release under real
119
+ child processes — each selected environment carrying the proofs its host owns;
120
+ - guide parity green over every app export and behavioral method;
121
+ - the repository gates green in their required order from an independent `verifier`.
122
+
123
+ A selected environment still unwired, a real-host proof not taken, or an open parity row
124
+ means the run is not finished. Report what each environment owns, the exact proof and gate
125
+ evidence, and any residual risk. Do not call an in-scope omission future work.
@@ -83,7 +83,7 @@ a practice that worked so it repeats.
83
83
  7. **Land the refinements.** Dispatch fix-now findings as bounded units under the
84
84
  repository's engine contract; make the canon edits (charters, rules, skills,
85
85
  orchestration contract) with the owner's direction where the root contract is
86
- touched; re-prove per the law above.
86
+ touched; re-prove per the re-proving law in § "The debrief laws".
87
87
  8. **Propagate.** Portable changes are made in the scaffold repository's host inventory,
88
88
  staged, gated, and pushed — editing one project's checkout propagates nothing. Verify
89
89
  the generated-workspace proofs stay green so new projects inherit the refined canon.
@@ -78,11 +78,9 @@ its coverage against it.
78
78
  Findings land as one of:
79
79
 
80
80
  - **Role create / restore / retire.** Retirement requires more than duplication evidence:
81
- when a charter merely restates rules, the first remedy is a thin reference-BINDING
81
+ when a charter merely restates rules, the first remedy is a thin reference-binding
82
82
  charter (the role keeps its context preset and its dispatch ergonomics); retire only
83
- when the job itself is not distinct. Record the lesson of the reversed retirement: a
84
- role that was "mechanically identical" by frontmatter still carried a distinct context
85
- bundle worth keeping.
83
+ when the job itself is not distinct.
86
84
  - **Rule additions, one law each.** A campaign lesson that generalizes becomes one law in
87
85
  the owning rule file — never a new file per lesson, never a paragraph where a sentence
88
86
  binds.
@@ -47,8 +47,9 @@ it. Follow `references/brief.md`. What this skill adds beyond the conduct law:
47
47
  politeness.
48
48
  - Unknowns are named as unknowns, with how the auditor reports back on them.
49
49
 
50
- The claim form itself is the Falsification law's — read it there. The **verdict shape** below is this
51
- skill's, because `.agents/orchestration.md` assigns it here; everything else about auditor conduct is the law's.
50
+ The claim form itself is the Falsification law's — read it there. The **verdict shape** in
51
+ § "Verdict shape" is this skill's, because `.agents/orchestration.md` assigns it here; everything
52
+ else about auditor conduct is the law's.
52
53
 
53
54
  ## Evidence, by subject type
54
55
 
@@ -114,15 +115,17 @@ nobody claimed.
114
115
  harder.** A fix round reviewed by the engine that wrote it is the case the round exists to avoid,
115
116
  and where the pass cannot avoid it, naming it is what recovers the round. A clean pass on its own
116
117
  engine's work is the least valuable result a lane can return.
117
- - Supply the evidence the subject type requires, per the table above.
118
+ - Supply the evidence the subject type requires, per § "Evidence, by subject type".
118
119
  - Auditors edit no source and spawn nothing. Read-only describes the SUBJECT, never the lane's
119
120
  tools.
120
- - **Read the lane's allowlist before writing its brief.** A lane with no write tool cannot create
121
- a probe; a lane with no exec tool cannot run one or read `git`. Naming either stops the unit on
122
- arrival over a detail the allowlist already settled.
123
- - Where the lane cannot execute, run the probe yourself, record its control and its output, and
124
- supply that record as the lane's evidence. The Orchestrator produces, the lane rules. Never
125
- widen a lane's tools to fit a brief.
121
+ - **Derive a lane's executable actions from its tool allowlist and its sandbox, and read both before
122
+ writing its brief.** A lane with no write tool cannot create a probe; a lane with no shell runs
123
+ none; a read-only filesystem does not forbid a nonmutating command. Naming an action the lane
124
+ cannot take stops the unit on arrival over a detail the allowlist and the sandbox already settled.
125
+ - Where an attack needs a tool the lane lacks or a write its sandbox refuses, run the probe
126
+ yourself, record its control and its output, and supply that record as the lane's evidence before
127
+ ruling on the claim. The Orchestrator produces, the lane rules. Never widen a lane's tools to fit
128
+ a brief.
126
129
  - Blind reports are **immutable**. Nothing an auditor returns is edited, merged, or revised — by
127
130
  anyone, including the auditor — once it has been returned.
128
131
 
@@ -22,9 +22,13 @@ established list is hearsay will re-derive all of it.
22
22
  dispatch deviation. For any claim about a rendered or externally driven surface, the capture is the
23
23
  evidence and source is corroboration.
24
24
 
25
- **Numbered falsifiable claims.** Each is a property some concrete input, state, or interleaving
26
- could show false. Assign the primary lane where auditors differ in strength, but do not let an
27
- auditor skip a claim because it assumes the other covers it better. The claim set is the round's
25
+ **Numbered falsifiable claims.** Write them to one file both lanes are pointed at,
26
+ `tmp/audit/<unit>-audit-claims.md`, retained beside the round's verdict. One file is what makes
27
+ "both lanes ran the same brief" checkable after the round, and each lane's own brief then carries
28
+ only its role, its lane, its evidence slice, and its output shape. Each claim is a property some
29
+ concrete input, state, or interleaving could show false. Assign the primary lane where auditors
30
+ differ in strength, but do not let an auditor skip a claim because it assumes the other covers it
31
+ better. The claim set is the round's
28
32
  scope: write it to cover what the subject owns, then hold it closed. An attack the round invents
29
33
  against something no claim names enters the verdict only when it is substantiated to the `BROKEN`
30
34
  standard; otherwise it is a claim for the successor brief, not a finding.
@@ -36,10 +40,11 @@ an executor inventing an answer and building on it silently.
36
40
  **The threshold.** State that a finding is worth more than a clean pass, and why: the alternative is
37
41
  a consumer finding it after publication, when the version is already spent.
38
42
 
39
- ## The read-only audit lane's brief
43
+ ## The audit lane's brief
40
44
 
41
- An audit lane writes nothing and runs nothing, so its brief carries fewer rows than a writing
42
- unit's. Give a lane every row § Anatomy names — the subject with the evidence
45
+ An audit lane changes no source, so its brief carries fewer rows than a writing unit's. `SKILL.md`
46
+ § "Run the round" fixes what a lane can execute; read it there before deciding which rows a lane
47
+ can use. Give a lane every row § Anatomy names — the subject with the evidence
43
48
  § "Evidence, by subject type" requires of each row it occupies, what the round decides, already
44
49
  established, the numbered falsifiable claims, the unknowns, and the threshold — plus its own
45
50
  **Role and lane** row (the role, its engine, and which lane it holds) and **Output** row (the
@@ -53,8 +58,11 @@ report.
53
58
 
54
59
  ## The successor rule
55
60
 
56
- A re-run **amends**; it never restates. Rewriting a brief from scratch loses the shape of what has
57
- already been attacked, and the round re-derives it at full cost.
61
+ A re-run takes a **successor brief** that carries the previous round forward. It never restates the
62
+ round from scratch and never edits the brief that already ran; `.agents/orchestration.md`
63
+ § "Every dispatch is a file before it is a launch" fixes the successor's name and its retention.
64
+ Rewriting a brief from scratch loses the shape of what has already been attacked, and the round
65
+ re-derives it at full cost.
58
66
 
59
67
  A successor brief:
60
68
 
@@ -5,8 +5,8 @@ decision, and it is not delegable.
5
5
 
6
6
  ## Reproduce before you act
7
7
 
8
- The rule beneath this whole section: **run it rather than argue it.** Every judgement below is
9
- cheap once the probe exists and unreliable until it does.
8
+ The rule beneath this whole section: **run it rather than argue it.** Every judgement that follows
9
+ is cheap once the probe exists and unreliable until it does.
10
10
 
11
11
  An auditor's finding is a **hypothesis** until the orchestrator has run it. Reproduce every sharp
12
12
  claim by hand, against the built output, before it enters a fix brief.
@@ -11,7 +11,7 @@ Read the current files in this order:
11
11
 
12
12
  1. `AGENTS.md`.
13
13
  2. Every applicable `.claude/rules/*.md`.
14
- 3. Select the work lane below and read every reference that lane requires.
14
+ 3. Select the work lane § "Select the work lane" names, and read every reference that lane requires.
15
15
  4. `guides/README.md`, the governing package/domain guide, and `ROADMAP.md` when present.
16
16
  5. The authoritative `*/types.ts`, public barrels, `package.json`, build/test configuration, and decision-bearing implementation files.
17
17
 
@@ -56,7 +56,8 @@ confirmed finding in scope and rebuilding the harness gaps the verdicts expose.
56
56
  2. **Seed candidates.** Turn your own mid-integration observations into numbered
57
57
  confirm-or-refute candidates inside the verdict brief. Observations that stay in your
58
58
  head are neither evidence nor findings.
59
- 3. **Take independent verdicts** on the SAME portfolio, in the fixed shape below. The
59
+ 3. **Take independent verdicts** on the SAME portfolio, in the shape
60
+ § "Return the fixed verdict shape" fixes. The
60
61
  lanes are subjective design fit; objective state truth; and mechanical inventory of
61
62
  copy, classes, icons, and accessibility attributes. This is the surface variant of the
62
63
  adversarial pass in `.agents/orchestration.md`, so its rules bind: each lane is a fresh
@@ -25,20 +25,24 @@ Read the current files in this order:
25
25
  9. The `*/types.ts` of every environment the journeys drive, plus the application's root component,
26
26
  route entry, and store contract.
27
27
 
28
+ Treat a retained readiness verdict as evidence to re-verify against the current tip, never as a plan
29
+ to resume. Re-take every ruling it records that this run's acceptance depends on, and name the commit
30
+ each ruling was taken at.
31
+
28
32
  ## Declare the families
29
33
 
30
34
  Declare in the browser environment's `integration.test.ts` which families that surface carries, and
31
35
  assert in the always-on proofs that every declared family is present. A declaration names which
32
36
  families a surface owes. It never switches what a declared family proves.
33
37
 
34
- | Family | Declared | Proves |
35
- | ---------- | --------------------------------------------------- | ---------------------------------------------------------------------- |
36
- | Journey | Always | Each user intent reaches its outcome through the interface |
37
- | Refusal | Always | Each control the surface withholds, through one exact failure voice |
38
- | Matrix | Where the surface ships more than one variant | The values the browser resolved under each declared variant |
39
- | Statechart | Where a journey drives a control that carries state | Each declared transition, driven through the interface where it can be |
40
- | Transport | Where the surface persists or restarts | Persistence, restart, and storage failure through real implementations |
41
- | Capture | Under the capture flag | The registry times the variants, each registered file written to disk |
38
+ | Family | Declared | Proves |
39
+ | ---------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
40
+ | Journey | Always | Each user intent reaches its outcome through the interface |
41
+ | Refusal | Always | Each control the surface withholds, through one exact failure voice |
42
+ | Matrix | Where the surface ships more than one variant | The values the browser resolved under each declared variant |
43
+ | Statechart | Where a journey drives a transition of an entity carrying its own state and event vocabulary | Each declared transition, driven through the interface where it can be |
44
+ | Transport | Where the surface persists or restarts | Persistence, restart, and storage failure through real implementations |
45
+ | Capture | Under the capture flag | The registry times the variants, each registered file written to disk |
42
46
 
43
47
  - Refuse a declaration that omits a family whose trigger the surface meets. Report the omission as a
44
48
  scope finding and stop; never prove the remaining families around it.
@@ -81,6 +85,10 @@ naming a combination the run did not render.
81
85
  observe as a surface finding, and never work around it in the layer.
82
86
  7. **Type only what a person would.** Journeys carry trusted input; adversarial payloads belong to
83
87
  the transport family and the parser suites.
88
+ 8. **Perform every interaction step unconditionally.** Never gate a step on whether the control it
89
+ is about to drive exists or is reachable, and never branch a journey on `readRefusal`. Let the
90
+ resolver's failure voice name what the interface withheld. A guarded step passes whether or not
91
+ the control was there, so the run goes green on a surface that removed the control.
84
92
 
85
93
  ## Import the journey layer
86
94
 
@@ -113,6 +121,9 @@ placement and scope `.claude/rules/tests.md` fixes.
113
121
  a harmless transient over-refuses and breaks on the next honest implementation.
114
122
  - Assert the negative beside the positive whenever a value replaces another: the new sentence is
115
123
  present **and** the old one is gone.
124
+ - Assert the state a control announces beside every drive that sets it, and on an unselected
125
+ sibling. A control announcing state owes this assertion whether or not the surface carries the
126
+ statechart family.
116
127
  - After a confirmed destructive action, assert through trusted input that focus landed on a visible,
117
128
  announced location.
118
129
  - Assert the whole page's perception never matches the vocabulary the product does not speak —