@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.
- package/dist/host/CLAUDE.md +3 -3
- package/dist/host/agents/orchestration.md +66 -32
- package/dist/host/agents/skills/enterprise-bootstrap/references/bootstrap-reference.md +36 -6
- package/dist/host/agents/skills/enterprise-bootstrap/references/color-modes.md +3 -2
- package/dist/host/agents/skills/enterprise-bootstrap/references/components.md +1 -1
- package/dist/host/agents/skills/orkestrel-build-application/SKILL.md +18 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +2 -4
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +12 -9
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +16 -8
- package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +2 -2
- package/dist/host/agents/skills/orkestrel-harden-package/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-polish-surface/SKILL.md +2 -1
- package/dist/host/agents/skills/orkestrel-prove-journey/SKILL.md +19 -8
- package/dist/host/agents/skills/orkestrel-prove-journey/references/layer.md +16 -15
- package/dist/host/agents/skills/orkestrel-prove-journey/references/statechart.md +5 -2
- package/dist/host/agents/skills/orkestrel-prove-journey/references/styles.md +5 -1
- package/dist/host/agents/templates/brief.md +4 -3
- package/dist/host/agents/transports/claude.md +13 -6
- package/dist/host/agents/transports/codex.md +2 -2
- package/dist/host/agents/transports/cursor.md +85 -0
- package/dist/host/claude/agents/application.md +5 -6
- package/dist/host/claude/agents/builder.md +3 -13
- package/dist/host/claude/agents/checker.md +9 -2
- package/dist/host/claude/agents/distiller.md +37 -0
- package/dist/host/claude/agents/grok.md +9 -56
- package/dist/host/claude/agents/{implementer.md → opus.md} +8 -9
- package/dist/host/claude/agents/orkestrel.md +7 -0
- package/dist/host/claude/agents/planner.md +12 -5
- package/dist/host/claude/agents/researcher.md +7 -0
- package/dist/host/claude/agents/reviewer.md +14 -7
- package/dist/host/claude/agents/scout.md +8 -1
- package/dist/host/claude/agents/sol.md +5 -5
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/writing.md +27 -24
- package/dist/host/claude/skills/orkestrel-build-application/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +10 -4
- package/dist/host/codex/agents/application.toml +5 -6
- package/dist/host/codex/agents/builder.toml +5 -5
- package/dist/host/codex/agents/checker.toml +4 -0
- package/dist/host/codex/agents/distiller.toml +28 -0
- package/dist/host/codex/agents/grok.toml +27 -19
- package/dist/host/codex/agents/opus.toml +5 -4
- package/dist/host/codex/agents/orkestrel.toml +5 -0
- package/dist/host/codex/agents/planner.toml +10 -0
- package/dist/host/codex/agents/researcher.toml +4 -0
- package/dist/host/codex/agents/reviewer.toml +12 -2
- package/dist/host/codex/agents/scout.toml +5 -2
- package/dist/host/codex/agents/{implementer.toml → sol.toml} +5 -6
- package/dist/host/codex/agents/verifier.toml +3 -0
- package/dist/host/codex/config.toml +2 -2
- package/dist/host/configs/policy.ts +5 -2
- package/dist/host/manifest.json +74 -56
- package/dist/src/core/index.cjs +448 -349
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +22 -21
- package/dist/src/core/index.d.ts +22 -21
- package/dist/src/core/index.js +448 -349
- package/dist/src/core/index.js.map +1 -1
- package/package.json +4 -4
package/dist/host/CLAUDE.md
CHANGED
|
@@ -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
|
|
31
|
-
|
|
32
|
-
|
|
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` | `
|
|
159
|
-
| Nontrivial implementation (subjective) | `
|
|
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
|
-
- `
|
|
171
|
-
|
|
172
|
-
|
|
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
|
|
181
|
-
Dispatch `grok` with their brief before using them, and use the native role only
|
|
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
|
|
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
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
-
|
|
436
|
-
|
|
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.
|
|
457
|
-
the
|
|
458
|
-
|
|
459
|
-
|
|
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.**
|
|
523
|
-
|
|
524
|
-
|
|
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`,
|
|
537
|
-
|
|
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
|
|
633
|
-
bench exec hanging on `npm` until its cap fires is the
|
|
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
|
|
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
|
|
118
|
-
for validated preference, automatic-mode resolution,
|
|
119
|
-
|
|
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
|
|
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
|
|
261
|
-
`
|
|
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 (
|
|
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:
|
|
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
|
|
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-
|
|
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.
|
|
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**
|
|
51
|
-
skill's, because `.agents/orchestration.md` assigns it here; everything
|
|
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
|
|
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
|
-
- **
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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.**
|
|
26
|
-
|
|
27
|
-
|
|
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
|
|
43
|
+
## The audit lane's brief
|
|
40
44
|
|
|
41
|
-
An audit lane
|
|
42
|
-
|
|
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
|
|
57
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
35
|
-
| ---------- |
|
|
36
|
-
| Journey | Always
|
|
37
|
-
| Refusal | Always
|
|
38
|
-
| Matrix | Where the surface ships more than one variant
|
|
39
|
-
| Statechart | Where a journey drives a
|
|
40
|
-
| Transport | Where the surface persists or restarts
|
|
41
|
-
| Capture | Under the capture flag
|
|
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 —
|