@orkestrel/scaffold 0.0.44 → 0.0.46
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/README.md +10 -10
- package/dist/bin/main.js +31 -31
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +7 -2
- package/dist/host/agents/orchestration.md +232 -56
- package/dist/host/agents/skills/enterprise-bootstrap/SKILL.md +7 -7
- package/dist/host/agents/skills/enterprise-bootstrap/references/bootstrap-reference.md +11 -9
- package/dist/host/agents/skills/enterprise-bootstrap/references/components.md +3 -3
- package/dist/host/agents/skills/enterprise-bootstrap/references/frontend-design.md +3 -3
- package/dist/host/agents/skills/enterprise-bootstrap/references/utilities.md +1 -1
- package/dist/host/agents/skills/orkestrel-align-packages/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-build-application/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/references/field-testing.md +2 -2
- package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +8 -8
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +16 -14
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +3 -3
- package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +14 -14
- package/dist/host/agents/skills/orkestrel-harden-package/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-human-journey/SKILL.md +3 -3
- package/dist/host/agents/skills/orkestrel-human-journey/references/captures.md +3 -3
- package/dist/host/agents/skills/orkestrel-human-journey/references/layer.md +3 -3
- package/dist/host/agents/skills/orkestrel-polish-surface/SKILL.md +3 -3
- package/dist/host/claude/agents/analyst.md +2 -2
- package/dist/host/claude/agents/checker.md +2 -2
- package/dist/host/claude/agents/codex.md +5 -5
- package/dist/host/claude/agents/orkestrel.md +10 -8
- package/dist/host/claude/agents/planner.md +1 -1
- package/dist/host/claude/agents/researcher.md +2 -2
- package/dist/host/claude/agents/reviewer.md +1 -1
- package/dist/host/claude/agents/scout.md +2 -2
- package/dist/host/claude/agents/sol.md +3 -3
- package/dist/host/claude/agents/verifier.md +8 -0
- package/dist/host/claude/rules/application.md +7 -7
- package/dist/host/claude/rules/architecture.md +6 -6
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/patterns.md +3 -3
- package/dist/host/claude/rules/quality.md +3 -3
- package/dist/host/claude/rules/tests.md +9 -2
- package/dist/host/claude/rules/workspace.md +7 -7
- package/dist/host/claude/rules/writing.md +12 -2
- package/dist/host/codex/agents/planner.toml +1 -1
- package/dist/host/codex/config.toml +4 -0
- package/dist/host/configs/helpers.ts +21 -1
- package/dist/host/cursor/mcp.json +4 -0
- package/dist/host/cursor/rules/orchestration.mdc +1 -1
- package/dist/host/dotfiles/gitignore +4 -1
- package/dist/host/dotfiles/mcp.json +4 -0
- package/dist/host/guides/scaffold.md +134 -119
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/host/tests/config.test.ts +40 -1
- package/dist/host/tests/policy.test.ts +2 -2
- package/dist/host/tests/setupPolicy.ts +8 -5
- package/dist/src/core/index.cjs +144 -149
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1624 -1643
- package/dist/src/core/index.d.ts +1624 -1643
- package/dist/src/core/index.js +145 -149
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +82 -97
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +1844 -1871
- package/dist/src/server/index.d.ts +1844 -1871
- package/dist/src/server/index.js +83 -96
- package/dist/src/server/index.js.map +1 -1
- package/package.json +4 -3
|
@@ -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
|
|
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)
|
|
18
18
|
- [RTL](#rtl)
|
|
19
19
|
- [Print](#print)
|
|
20
20
|
- [Performance](#performance)
|
|
@@ -129,7 +129,7 @@ In Sass: `$enable-dark-mode` (default true), `$color-mode-type: data` (attribute
|
|
|
129
129
|
|
|
130
130
|
## Theming & Design Tokens
|
|
131
131
|
|
|
132
|
-
### The
|
|
132
|
+
### The tiered token model
|
|
133
133
|
|
|
134
134
|
Enterprise theming survives rebrands and dark mode only when tokens are tiered:
|
|
135
135
|
|
|
@@ -211,7 +211,7 @@ Remove with `map-remove($utilities, "width")` or set the key to `null`. This is
|
|
|
211
211
|
|
|
212
212
|
- **Top-aligned labels by default** — the evidence (eye-tracking form research) shows fastest completion and the cleanest single-column scan, and they survive narrow screens without reflow. Reserve left-aligned labels for dense read-back forms where vertical compression matters more than speed.
|
|
213
213
|
- Visible label or `.form-floating` — never placeholder-only (disappears on input, fails accessibility).
|
|
214
|
-
- **Do not say the same thing twice.** When the host already names the request — a card heading, a dialog title, a section header stating the question — the form associates with that name via `aria-labelledby` instead of repeating the prompt in its own label. Repetition reads as
|
|
214
|
+
- **Do not say the same thing twice.** When the host already names the request — a card heading, a dialog title, a section header stating the question — the form associates with that name via `aria-labelledby` instead of repeating the prompt in its own label. Repetition reads as separate questions to a screen-reader user and as clutter to everyone else.
|
|
215
215
|
- One column beats multi-column for completion; use the form grid (`row g-3` + `col-md-*`) only for genuinely paired fields (city/state/zip).
|
|
216
216
|
|
|
217
217
|
```html
|
|
@@ -508,19 +508,21 @@ Give header cells an **opaque background** (`bg-body-secondary` or a table varia
|
|
|
508
508
|
- One toolbar above the table: search input first (`role="search"` on the form), then the 2–4 highest-value filters as `form-select`/segmented controls, overflow filters behind a "Filters" button (offcanvas on mobile, dropdown/collapse on desktop).
|
|
509
509
|
- **Active filters must be visible and dismissible** — chips/badges with an ✕ and a "Clear all" — users must see _why_ the list is short. A filtered-empty state repeats the escape hatch.
|
|
510
510
|
- Debounce live search; show result counts ("128 results") so feedback is immediate; filter state belongs in the URL when views are shareable.
|
|
511
|
-
- Toolbars that overflow: `flex-nowrap overflow-auto` beats wrapping
|
|
511
|
+
- Toolbars that overflow: `flex-nowrap overflow-auto` beats wrapping the toolbar onto a second row mid-task — do not crush icon targets below 24px.
|
|
512
512
|
|
|
513
513
|
### Wizards & multi-step forms
|
|
514
514
|
|
|
515
|
-
- Show step progress: current position, total, and step
|
|
515
|
+
- Show step progress: current position, total, and step name (for example, "Billing — step ⟨n⟩ of
|
|
516
|
+
⟨total⟩", where the wizard fills in its own runtime position and total); `list-group-numbered` or
|
|
517
|
+
a simple nav renders it honestly.
|
|
516
518
|
- Validate per step before advancing; never let a step advance carrying invalid data.
|
|
517
519
|
- Back never loses data. Persist partial state (save-and-resume) for anything beyond ~3 steps or that crosses sessions.
|
|
518
520
|
- Never re-ask what a previous step collected (Redundant Entry, 3.3.7) — carry it forward or offer "same as above".
|
|
519
|
-
-
|
|
521
|
+
- Review step: a review summary with per-section edit links, then one clearly-named commit action ("Create account", not "Submit").
|
|
520
522
|
|
|
521
|
-
### The
|
|
523
|
+
### The data states
|
|
522
524
|
|
|
523
|
-
Design **
|
|
525
|
+
Design **every one** for every data surface: ideal (populated), empty, loading, partial, error. A component is not done until all of them exist.
|
|
524
526
|
|
|
525
527
|
- **Skeleton vs spinner:** skeleton (`placeholder` + `placeholder-glow`) when you know the content's shape and it fills a region — tables, cards, detail panes — because it holds layout and shortens perceived wait. Spinner for short, indeterminate, or in-control waits (inside a button, a small inline fetch).
|
|
526
528
|
- **Thresholds (guidance):** under ~1s show nothing — a flashed loader is worse than none; ~1–10s show a spinner or skeleton; beyond ~10s show determinate progress (percent or step) so it does not feel hung.
|
|
@@ -565,7 +567,7 @@ Do not type-gate a single-row delete; do not one-tap a tenant wipe. Confirm only
|
|
|
565
567
|
|
|
566
568
|
## Performance
|
|
567
569
|
|
|
568
|
-
- **Ship one CSS system
|
|
570
|
+
- **Ship one CSS system and no more.** Bootstrap plus a second framework (or a parallel bespoke layer) doubles payload and guarantees specificity fights.
|
|
569
571
|
- **Compressed, the full build is cheap; incomplete builds are not.** Trimming via a Sass-subset build (import only the parts used — see [Theming](#theming--design-tokens)) is the sanctioned diet. Aggressive purge tools are the risky one: Bootstrap adds classes **at runtime** (`show`, `showing`, `fade`, `collapsing`, `modal-open`, `modal-backdrop`, `offcanvas-backdrop`, tooltip/popover generated markup) — purging without safelisting them ships UIs whose modals silently stop rendering. If you purge, safelist every JS-toggled class and test every overlay.
|
|
570
572
|
- **Icons:** Bootstrap Icons is a separate package — prefer inline SVG or an SVG sprite (crisp, styleable via `currentColor`, no font flash) over the icon font; load only the icons used.
|
|
571
573
|
- **JS:** the bundle is small, but only load it where behavior exists; per-component ESM imports (`bootstrap/js/dist/modal`) trim further in bundlers.
|
|
@@ -423,7 +423,7 @@ Multiple targets: give each panel `.multi-collapse` and point separate triggers
|
|
|
423
423
|
</dialog>
|
|
424
424
|
```
|
|
425
425
|
|
|
426
|
-
`role="alertdialog"` for a destructive confirm, `role="dialog"` otherwise; `aria-labelledby` points at the heading. The element's own `close` event is where the host clears the state that opened it, so Esc and the buttons all close by one path. The scrim is the UA's `::backdrop`, which no Bootstrap class touches — restyling it
|
|
426
|
+
`role="alertdialog"` for a destructive confirm, `role="dialog"` otherwise; `aria-labelledby` points at the heading. The element's own `close` event is where the host clears the state that opened it, so Esc and the buttons all close by one path. The scrim is the UA's `::backdrop`, which no Bootstrap class touches — restyling it requires the custom-CSS tier.
|
|
427
427
|
|
|
428
428
|
Bootstrap's `.modal` is the answer when the project already drives its dialogs through Bootstrap's JS:
|
|
429
429
|
|
|
@@ -670,7 +670,7 @@ Real switchable tab panels (JS-driven — buttons, not scroll anchors):
|
|
|
670
670
|
<button class="btn btn-primary disabled placeholder col-4" aria-hidden="true"></button>
|
|
671
671
|
```
|
|
672
672
|
|
|
673
|
-
Always wrap skeletons in `aria-hidden="true"` — they are visual scaffolding, not content. Skeleton-vs-spinner decision rules: [bootstrap-reference.md](bootstrap-reference.md) → The
|
|
673
|
+
Always wrap skeletons in `aria-hidden="true"` — they are visual scaffolding, not content. Skeleton-vs-spinner decision rules: [bootstrap-reference.md](bootstrap-reference.md) → The data states.
|
|
674
674
|
|
|
675
675
|
### Popover (Requires Popper.js)
|
|
676
676
|
|
|
@@ -1002,7 +1002,7 @@ The textless mark that survives both themes — dots, ticks, rings, pulses — i
|
|
|
1002
1002
|
|
|
1003
1003
|
### Selection fills
|
|
1004
1004
|
|
|
1005
|
-
A selected row, pill, or filter chip repaints everything inside it — marks included.
|
|
1005
|
+
A selected row, pill, or filter chip repaints everything inside it — marks included. These traps stay invisible until the selected state is captured in both themes:
|
|
1006
1006
|
|
|
1007
1007
|
- **A mark on an active fill of the same family disappears.** `.active` on a `list-group-item`, `nav-pill`, or `page-item` sets the item's own color, and a `text-bg-primary`-family mark inside it inherits or loses to that fill — present in the markup, gone on screen. Carry no tone class inside the fill ([SKILL.md](../SKILL.md) → Surfaces, color, contrast). Verify by capturing the selected row, not by reading the class list.
|
|
1008
1008
|
- **`btn-check` filter labels invert in dark.** A `btn-outline-secondary` label reads as "chosen" in light and as "muted" in dark, because the checked fill and the surface swap relative weight. Give chosen filters an accent variant (a real theme color) rather than the neutral outline, so "chosen" reads the same way in both modes.
|
|
@@ -57,17 +57,17 @@ product's, and keep the data surfaces disciplined and conventional enough to rea
|
|
|
57
57
|
|
|
58
58
|
## Process: brainstorm, explore, plan, critique, build, critique again
|
|
59
59
|
|
|
60
|
-
Calibrate against the
|
|
60
|
+
Calibrate against the looks AI-generated design currently clusters around: (1) a warm cream
|
|
61
61
|
background (near #F4F1EA) with a high-contrast serif display and a terracotta accent; (2) a
|
|
62
62
|
near-black background with a single bright acid-green or vermilion accent; (3) a broadsheet-style
|
|
63
|
-
layout with hairline rules, zero border-radius, and dense newspaper-like columns.
|
|
63
|
+
layout with hairline rules, zero border-radius, and dense newspaper-like columns. Each is
|
|
64
64
|
legitimate for some briefs; they are defaults rather than choices, and they appear regardless of
|
|
65
65
|
subject. Follow the brief exactly where it pins a visual direction — the brief's own words always
|
|
66
66
|
win, including when they ask for one of these looks. Where the brief leaves an axis free, spend that
|
|
67
67
|
freedom somewhere other than these defaults. Balance the moves you have already proven against
|
|
68
68
|
experimenting where the brief invites it.
|
|
69
69
|
|
|
70
|
-
Work in
|
|
70
|
+
Work in passes. First, brainstorm a short design plan from the brief: a compact token system
|
|
71
71
|
with color, type, layout, and signature. Color: describe the palette as 4–6 named hex values. Type:
|
|
72
72
|
name the typefaces for 2+ roles — a characterful display face used with restraint, a complementary
|
|
73
73
|
body face, and a utility face for captions or data where one is needed. Layout: state a layout
|
|
@@ -226,7 +226,7 @@ Notes: `s`/`e` are logical start/end — they flip automatically under RTL; neve
|
|
|
226
226
|
.text-truncate
|
|
227
227
|
```
|
|
228
228
|
|
|
229
|
-
|
|
229
|
+
The composition traps in this group:
|
|
230
230
|
|
|
231
231
|
- **`fs-*` without `lh-1` grows the row.** A resized glyph or mark keeps the parent's line-height, so the line box stretches and the row sits taller than its neighbors. Pair `fs-*` with `lh-1` on anything that is a mark rather than a paragraph.
|
|
232
232
|
- **`text-truncate` zeroes a flex item's automatic minimum size** (that's the `min-width: 0` it carries). Inside a flex _column_, that also removes the floor that kept a heading at its own height: a growing sibling then squeezes the title from the bottom until it clips. Floor the title with `flex-shrink-0` and let the growing sibling absorb the change.
|
|
@@ -36,7 +36,7 @@ Invoke `$orkestrel-harden-package` for each package implementation unit. This sk
|
|
|
36
36
|
8. **Prove the round trip.** Put integration coverage at the highest package that can exercise the real composed behavior. Retain focused deterministic coverage in lower packages.
|
|
37
37
|
9. **Validate local changes safely.** When necessary, use built artifacts in an isolated consumer and prove the resolved graph. Restore temporary manifest/lockfile state.
|
|
38
38
|
10. **Verify topologically.** Run local gates for touched packages from dependencies to dependents and inspect relevant generated outputs.
|
|
39
|
-
11. **Review the campaign.** Run the
|
|
39
|
+
11. **Review the campaign.** Run the adversarial pass plus a mechanical checker on each implementation unit, then one cross-package architecture and ergonomics review over the whole graph.
|
|
40
40
|
|
|
41
41
|
## Accept the result
|
|
42
42
|
|
|
@@ -73,7 +73,7 @@ includes app/core so the shared transport contracts have one host-independent ow
|
|
|
73
73
|
callbacks reject forced inlining before any direct asset read, and non-inlined
|
|
74
74
|
output assets are audited by physical source path.
|
|
75
75
|
|
|
76
|
-
Then hold these
|
|
76
|
+
Then hold these limits:
|
|
77
77
|
- Add no standalone boundary script, and no second parser or source-language analyzer
|
|
78
78
|
duplicating those layers. Reach for the toolchain's own facilities instead: Vite's
|
|
79
79
|
Oxc/Rolldown AST for TypeScript and JavaScript asset references, the official Vue SFC
|
|
@@ -98,7 +98,7 @@ includes app/core so the shared transport contracts have one host-independent ow
|
|
|
98
98
|
8. **Document and prove parity** for every app export and behavioral method: guide,
|
|
99
99
|
examples, manifest index, and the parity specifiers walking the existing `src` and
|
|
100
100
|
`app` roots and every selected alias.
|
|
101
|
-
9. **Verify.** Run the rules' cleanup sweeps over source and tests. Then run the
|
|
101
|
+
9. **Verify.** Run the rules' cleanup sweeps over source and tests. Then run the
|
|
102
102
|
adversarial pass, a mechanical conformance pass, and the repository gates in their
|
|
103
103
|
required order. Generated CI runs those gates on the declared minimum Node release and
|
|
104
104
|
on the current major.
|
|
@@ -75,7 +75,7 @@ a practice that worked so it repeats.
|
|
|
75
75
|
[instruction-audit.md](references/instruction-audit.md). What confused an executor is
|
|
76
76
|
a defect in the instruction, not the executor.
|
|
77
77
|
6. **Reconcile into the ledger.** Number the findings, attach verbatim evidence, bucket
|
|
78
|
-
every one. Where
|
|
78
|
+
every one. Where audit lanes disagree, rule each divergence on the record with
|
|
79
79
|
the reason.
|
|
80
80
|
7. **Land the refinements.** Dispatch fix-now findings as bounded units under the
|
|
81
81
|
repository's engine contract; make the canon edits (charters, rules, skills,
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Field testing an agent-facing surface
|
|
2
2
|
|
|
3
|
-
The method for producing the live evidence a debrief judges by.
|
|
4
|
-
|
|
3
|
+
The method for producing the live evidence a debrief judges by. It ports to any surface a
|
|
4
|
+
model consumes.
|
|
5
5
|
|
|
6
6
|
## The tier ladder
|
|
7
7
|
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Auditing the instruction set
|
|
2
2
|
|
|
3
3
|
The method for judging the agents, rules, skills, and orchestration contract against a
|
|
4
|
-
campaign's record.
|
|
5
|
-
|
|
4
|
+
campaign's record. The instruction layer is code — it gets the same adversarial,
|
|
5
|
+
evidence-first treatment as any surface.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Blind passes, one brief
|
|
8
8
|
|
|
9
9
|
Run a subjective lane and an objective lane on the SAME brief, in parallel, neither
|
|
10
10
|
seeing the other's answer before both return:
|
|
@@ -27,11 +27,11 @@ record.
|
|
|
27
27
|
## The objective lanes
|
|
28
28
|
|
|
29
29
|
- **Duplication diff.** Whole-line and obligation-level comparison across charters, rules,
|
|
30
|
-
and skills. A charter that restates a rule drifts from it; a rule
|
|
31
|
-
|
|
30
|
+
and skills. A charter that restates a rule drifts from it; a rule restated elsewhere has
|
|
31
|
+
more than one owner.
|
|
32
32
|
- **Mechanical-equivalence groups.** Cluster roles by frontmatter (tools, model, effort,
|
|
33
|
-
mode).
|
|
34
|
-
|
|
33
|
+
mode). Roles in one group are either genuinely distinct by context binding — or
|
|
34
|
+
duplicates.
|
|
35
35
|
- **Charter-versus-usage drift.** For each role, compare the charter's promises against
|
|
36
36
|
how the campaign actually dispatched it: unused powers, exercised powers the charter
|
|
37
37
|
never granted, deviation reports the charter's wording caused.
|
|
@@ -69,7 +69,7 @@ Findings land as one of:
|
|
|
69
69
|
probe-first, journal-first, verdict shapes, launch ownership) land in the operating
|
|
70
70
|
contract, mirrored across providers.
|
|
71
71
|
|
|
72
|
-
##
|
|
72
|
+
## The questions every round asks
|
|
73
73
|
|
|
74
74
|
- **Which findings came from falsification rather than diff reading**, and is the brief
|
|
75
75
|
shape that produced them doctrine yet? Route to the Falsification law in
|
|
@@ -58,7 +58,7 @@ diff is a rule the brief cannot satisfy.
|
|
|
58
58
|
| a policy, design, or process proposal | the proposal, the canon it must satisfy, and the record of what motivated it |
|
|
59
59
|
|
|
60
60
|
**A subject can occupy more than one row; supply every row it occupies.** A ruling whose fixes
|
|
61
|
-
already landed as edits is both
|
|
61
|
+
already landed as edits is both a proposal and a code change, and withholding the diff on the grounds
|
|
62
62
|
that the subject is "a proposal" leaves the auditor unable to check whether a fix changed anything
|
|
63
63
|
nobody claimed.
|
|
64
64
|
|
|
@@ -69,21 +69,22 @@ nobody claimed.
|
|
|
69
69
|
looking like authority — and it fails silently, because an auditor does not report a heading it
|
|
70
70
|
never saw. Check before dispatch; propagate the missing file rather than restating its contents in
|
|
71
71
|
the brief. This is the reason restatement felt necessary, and it is the wrong cure.
|
|
72
|
-
- Run the **
|
|
72
|
+
- Run the **adversarial pass** on one identical brief: a subjective lane and an objective
|
|
73
73
|
lane, each a fresh subagent with a clean context, blind to each other. Reconcile them yourself.
|
|
74
74
|
`.agents/orchestration.md` owns lane definitions, engine assignment, and what happens when an
|
|
75
75
|
engine is dark; do not restate them here.
|
|
76
76
|
- A round run with one lane is a deviation. Record it rather than glossing it. If an engine is
|
|
77
|
-
unavailable, the remaining engine runs
|
|
78
|
-
- **Pair every finder with an independent refuter when the round fans out past
|
|
77
|
+
unavailable, the remaining engine runs every lane — it never drops one.
|
|
78
|
+
- **Pair every finder with an independent refuter when the round fans out past the subjective and
|
|
79
|
+
objective lanes.** The
|
|
79
80
|
refuter receives one slice's findings, never that finder's work, and is briefed to BREAK them
|
|
80
81
|
rather than to re-audit the subject. It reproduces each stated vector itself and defaults to
|
|
81
82
|
refuted when uncertain.
|
|
82
|
-
- Refute on any of
|
|
83
|
+
- Refute on any of these grounds, and name which: the vector does not reproduce; the behaviour is
|
|
83
84
|
correct and documented; it is unreachable through the public API or a documented seam; it asks
|
|
84
85
|
for new capability rather than naming a defect; it restates a finding an earlier round
|
|
85
86
|
repaired; or its diagnosis is wrong — then CONFIRM with the correction.
|
|
86
|
-
- Only a survivor earns a fix unit. An unrefuted finding is a hypothesis. The
|
|
87
|
+
- Only a survivor earns a fix unit. An unrefuted finding is a hypothesis. The scope grounds,
|
|
87
88
|
unreachable and new capability, are what keep a round from drifting into a redesign.
|
|
88
89
|
- **Give every auditor the means to run its attacks.** A lens that can only read returns derivations,
|
|
89
90
|
and a derivation reads exactly like a verdict — it will confirm a claim that one probe would break.
|
|
@@ -124,7 +125,7 @@ nobody claimed.
|
|
|
124
125
|
Every auditor in every round returns exactly this, and nothing else. One shape makes rounds
|
|
125
126
|
comparable; a round that invents its own cannot be read against the last one.
|
|
126
127
|
|
|
127
|
-
1. **Numbered verdicts**, one per claim, in the brief's order. Exactly one of
|
|
128
|
+
1. **Numbered verdicts**, one per claim, in the brief's order. Exactly one of these values:
|
|
128
129
|
|
|
129
130
|
| value | meaning | evidence |
|
|
130
131
|
| --------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -133,10 +134,11 @@ comparable; a round that invents its own cannot be read against the last one.
|
|
|
133
134
|
| `UNRESOLVED` | cannot be decided from the evidence available | what would settle it |
|
|
134
135
|
| `NOT-EVIDENCED` | a claim about a rendered or externally driven surface the supplied capture cannot show | which capture is missing |
|
|
135
136
|
|
|
136
|
-
|
|
137
|
-
`BROKEN` and `UNRESOLVED` are **separate**: a claim nobody could
|
|
138
|
-
and it cannot supply the fields falsification requires.
|
|
139
|
-
`analyst` and `reviewer` charters already require; it is kept,
|
|
137
|
+
`CONFIRMED` and `BROKEN` defer; only `UNRESOLVED` and `NOT-EVIDENCED` are this skill's, because
|
|
138
|
+
the law does not name them. `BROKEN` and `UNRESOLVED` are **separate**: a claim nobody could
|
|
139
|
+
decide has not been falsified, and it cannot supply the fields falsification requires.
|
|
140
|
+
`NOT-EVIDENCED` is the token the `analyst` and `reviewer` charters already require; it is kept,
|
|
141
|
+
not re-invented.
|
|
140
142
|
|
|
141
143
|
2. **Findings fitting no claim**, if any, each substantiated to the same standard as `BROKEN`.
|
|
142
144
|
|
|
@@ -147,7 +149,7 @@ comparable; a round that invents its own cannot be read against the last one.
|
|
|
147
149
|
VERDICT: FAIL — <n> broken, <u> unresolved, <e> not-evidenced, <x> findings outside the claims
|
|
148
150
|
```
|
|
149
151
|
|
|
150
|
-
**`PASS` requires
|
|
152
|
+
**`PASS` requires every one of these to be true**: every claim `CONFIRMED`, nothing `UNRESOLVED`, nothing
|
|
151
153
|
`NOT-EVIDENCED`, and no substantiated finding outside the claims. A single substantiated finding
|
|
152
154
|
forces `FAIL` no matter how the numbered claims landed — otherwise a round can report a real
|
|
153
155
|
defect and still emit the word that authorises the release.
|
|
@@ -173,8 +175,8 @@ Follow `references/reconcile.md`. The obligations that are not delegable:
|
|
|
173
175
|
vectors teaches the lane those vectors matter, and a lane can hand back the brief's own questions as
|
|
174
176
|
the subject's claims — demanding coverage for a property the subject never documented. Grep the
|
|
175
177
|
subject for the claim the finding rests on. Where it is not there, the finding is against the brief.
|
|
176
|
-
- **A disagreement between auditors is rarely a tie to average.** It is usually
|
|
177
|
-
to
|
|
178
|
+
- **A disagreement between auditors is rarely a tie to average.** It is usually correct answers
|
|
179
|
+
to different questions. Find the question each one answered.
|
|
178
180
|
- **Bound every finding**: state what is _not_ broken, and why the adjacent behaviour that looks the
|
|
179
181
|
same is correct. An audit that reports everything is as useless as one that reports nothing.
|
|
180
182
|
- **Bound the fix before briefing it.** Establish what over-correcting would break, and include that
|
|
@@ -78,9 +78,9 @@ repair to carry the next defect; a round that finds them is converging, not fail
|
|
|
78
78
|
- _"CONFIRMED requires naming the attack you tried that failed."_ — the single most effective
|
|
79
79
|
sentence, because it converts a confirmation from an opinion into a report of work done.
|
|
80
80
|
- _"A claim you cannot decide is UNRESOLVED, not CONFIRMED — say what would settle it."_
|
|
81
|
-
- _"Assume this chain has one more."_ —
|
|
82
|
-
|
|
83
|
-
- _"Do not hedge toward an imagined consensus."_ — when
|
|
81
|
+
- _"Assume this chain has one more."_ — naming the prior rounds and which of them a defect the
|
|
82
|
+
previous round believed closed provoked.
|
|
83
|
+
- _"Do not hedge toward an imagined consensus."_ — when auditors run blind, each will otherwise
|
|
84
84
|
soften toward what it guesses the other said.
|
|
85
85
|
|
|
86
86
|
Do **not** write _"an audit returning only confirmations has not tried."_ It reads as pressure to
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Reconciling a round and ruling on it
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The auditors return. Neither accepts; the orchestrator does. This is where a round becomes a
|
|
4
4
|
decision, and it is not delegable.
|
|
5
5
|
|
|
6
6
|
## Reproduce before you act
|
|
@@ -16,7 +16,7 @@ catch cannot distinguish _the subject threw_ from _my harness threw_ — a missi
|
|
|
16
16
|
arity, a `require` in an ESM context all surface as the finding you were hoping to see. Construct
|
|
17
17
|
first, let harness failures crash loudly, and only guard the call under test.
|
|
18
18
|
|
|
19
|
-
Reproduction produces
|
|
19
|
+
Reproduction produces these outcomes, and all of them matter:
|
|
20
20
|
|
|
21
21
|
- the finding **confirms** and is often **wider** than reported — the reproduction reaches doors the
|
|
22
22
|
auditor did not try;
|
|
@@ -32,18 +32,18 @@ code under test reports a pass that means nothing, and it will read exactly like
|
|
|
32
32
|
|
|
33
33
|
## A disagreement is rarely a tie
|
|
34
34
|
|
|
35
|
-
When
|
|
35
|
+
When auditors return opposite verdicts on one claim, do not average them and do not prefer the
|
|
36
36
|
engine you trust more. **Reproduce first** — running the disagreement settles most of them outright,
|
|
37
37
|
and it is the only method that can also find what neither auditor saw. Then find the question each
|
|
38
38
|
one answered. The common shapes:
|
|
39
39
|
|
|
40
40
|
- **Both right about different objects.** One tested a case the other did not construct. This is a
|
|
41
|
-
`SPLIT-CLAIM`: the claim was a universal that carried more than one subject. It is **not** a
|
|
42
|
-
verdict value — one falsifying input makes a universal claim `BROKEN`, and succeeding on a
|
|
41
|
+
`SPLIT-CLAIM`: the claim was a universal that carried more than one subject. It is **not** a
|
|
42
|
+
further verdict value — one falsifying input makes a universal claim `BROKEN`, and succeeding on a
|
|
43
43
|
different object does not undo that. Split it, keep the original `BROKEN` if any subclaim is
|
|
44
44
|
broken, and carry the split into the successor brief.
|
|
45
45
|
- **Both right about different halves of one claim number.** Same resolution: the claim number was
|
|
46
|
-
carrying
|
|
46
|
+
carrying more than one claim. Split and renumber.
|
|
47
47
|
- **One right on the mechanism, the other on the criterion.** Take both. The reconciled ruling is
|
|
48
48
|
frequently neither proposal, and better than either, because each supplied a constraint the other
|
|
49
49
|
violated.
|
|
@@ -60,7 +60,7 @@ memory. A reader six months out must be able to tell an unbiased blind verdict f
|
|
|
60
60
|
after an auditor saw its counterpart's evidence — otherwise the whole value of running blind is
|
|
61
61
|
unverifiable after the fact.
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
These rules are enforceable:
|
|
64
64
|
|
|
65
65
|
1. **A returned verdict is never edited** — not by the auditor, not by the orchestrator.
|
|
66
66
|
2. **Anything an auditor says after seeing another's report is a separate file beside that verdict**,
|
|
@@ -82,7 +82,7 @@ State what is **not** broken, and why the adjacent behaviour that looks identica
|
|
|
82
82
|
finding without a boundary is an alarm, and alarms get discounted wholesale — including the true
|
|
83
83
|
ones next to them.
|
|
84
84
|
|
|
85
|
-
|
|
85
|
+
These boundaries earn their keep:
|
|
86
86
|
|
|
87
87
|
- **Credit what the round got right.** If the hostile inputs adjacent to the hole are correctly
|
|
88
88
|
contained, say so and list them. It sharpens the finding to a point instead of an area.
|
|
@@ -95,8 +95,8 @@ Two boundaries earn their keep:
|
|
|
95
95
|
Establish what over-correcting would break, and put it in the fix brief as a constraint. Both ends
|
|
96
96
|
are usually wrong:
|
|
97
97
|
|
|
98
|
-
- **too little** — a patch to the one function, leaving the package holding
|
|
99
|
-
same thing, which is the inconsistency that produced the finding;
|
|
98
|
+
- **too little** — a patch to the one function, leaving the package holding conflicting standards
|
|
99
|
+
for the same thing, which is the inconsistency that produced the finding;
|
|
100
100
|
- **too much** — adopting the strictest sibling's rule verbatim, breaking a legitimate caller
|
|
101
101
|
pattern, and tripping "no refusal was widened into a regression" in the next round.
|
|
102
102
|
|
|
@@ -124,7 +124,7 @@ are easiest to construct. That sampling proves discrimination _within_ the popul
|
|
|
124
124
|
routinely reported as proof the instrument works.
|
|
125
125
|
|
|
126
126
|
So before running controls, write down the instrument's **membership rule** in one sentence, then
|
|
127
|
-
ask what the rule excludes. Draw at least one control from there.
|
|
127
|
+
ask what the rule excludes. Draw at least one control from there. These shapes have already cost a
|
|
128
128
|
round each:
|
|
129
129
|
|
|
130
130
|
- an AST comparison whose controls were all drawn from the literal classes present in the bodies it
|
|
@@ -132,9 +132,9 @@ round each:
|
|
|
132
132
|
- a call-closure pin whose controls were all body-reachable functions, green for a function reached
|
|
133
133
|
only through a parameter default.
|
|
134
134
|
|
|
135
|
-
Then write the
|
|
136
|
-
|
|
137
|
-
outruns its evidence.
|
|
135
|
+
Then write the sentences that matter: what the controls established, and what they did not. What
|
|
136
|
+
they did not establish is the one that gets skipped, and skipping it is how an instrument's
|
|
137
|
+
credibility outruns its evidence.
|
|
138
138
|
|
|
139
139
|
## Ruling
|
|
140
140
|
|
|
@@ -51,7 +51,7 @@ Load [hardening.md](references/hardening.md) for the hardening lane and for any
|
|
|
51
51
|
10. **Document the final behavior.** Update the governing guide, examples, method tables, limitations, and parity coverage. Document architectural limits honestly.
|
|
52
52
|
11. **Audit completion.** Inspect test discovery, `.todo`/`.skip`/conditional skip use, source/test helper duplication, exports, environment isolation, unexpected text corruption, and the entire diff.
|
|
53
53
|
12. **Verify.** Run the repository-prescribed gates in order and inspect the generated outputs relevant to the request.
|
|
54
|
-
13. **Review independently, and never by the author.** When orchestration is available, run the
|
|
54
|
+
13. **Review independently, and never by the author.** When orchestration is available, run the adversarial pass — subjective design fit and objective correctness — plus a mechanical checker, per `.agents/orchestration.md`. Add a dedicated adversarial round for security, concurrency, destructive paths, or external input. A unit's auditor is an engine that did not write it; same-engine re-review returns the author's own blind spot. Resolve every required finding, then rerun affected verification.
|
|
55
55
|
|
|
56
56
|
## Accept the result
|
|
57
57
|
|
|
@@ -78,15 +78,15 @@ placement and scope `.claude/rules/tests.md` fixes.
|
|
|
78
78
|
announced location.
|
|
79
79
|
- Assert the whole page's perception never matches the vocabulary the product does not speak —
|
|
80
80
|
engine, schema, and implementation words the interface is supposed to translate.
|
|
81
|
-
- Report a bare accessible name that answers for
|
|
81
|
+
- Report a bare accessible name that answers for more than one reachable element on one screen as a surface
|
|
82
82
|
finding, and target through role or region until the surface is fixed.
|
|
83
83
|
|
|
84
84
|
## Prove the refusals
|
|
85
85
|
|
|
86
86
|
- Give every surface a refusal family: the controls a person must not reach in the state the
|
|
87
87
|
journey has put the surface in.
|
|
88
|
-
- Assert the exact failure voice the case means. Never write an assertion that accepts
|
|
89
|
-
|
|
88
|
+
- Assert the exact failure voice the case means. Never write an assertion that accepts more than
|
|
89
|
+
one voice.
|
|
90
90
|
- Cover the restrictions the interface imposes on itself: a collapsed panel's field, a verb
|
|
91
91
|
belonging to another kind of object, a control disabled until its precondition lands.
|
|
92
92
|
- When a refusal changes voice after a markup change, read it as a role or reachability change
|
|
@@ -21,7 +21,7 @@ capture(state: string): Promise<string | undefined>
|
|
|
21
21
|
|
|
22
22
|
## The registry
|
|
23
23
|
|
|
24
|
-
Declare
|
|
24
|
+
Declare a frozen list of state names and a frozen list of variants in the journey file.
|
|
25
25
|
|
|
26
26
|
- Name a state for its surface and its condition — `answer-partial`, `start-storage-failure`,
|
|
27
27
|
`case-delete-confirmation`.
|
|
@@ -35,12 +35,12 @@ Declare two frozen lists in the journey file: the state names, and the variants.
|
|
|
35
35
|
## Variants
|
|
36
36
|
|
|
37
37
|
- Name a variant as one value carrying both the theme and the viewport, such as `dark-390`. Never
|
|
38
|
-
split them into
|
|
38
|
+
split them into separate selectors: a split lets a run write a filename describing a combination it
|
|
39
39
|
did not render.
|
|
40
40
|
- Render one variant per run, and produce the portfolio — the registry times the variants — by
|
|
41
41
|
repeating the run once per variant.
|
|
42
42
|
|
|
43
|
-
## The
|
|
43
|
+
## The proofs
|
|
44
44
|
|
|
45
45
|
| Proof | Runs | Asserts |
|
|
46
46
|
| -------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
@@ -42,7 +42,7 @@ resolveAccessible(role: string, name: string): HTMLElement
|
|
|
42
42
|
|
|
43
43
|
### The failure voices
|
|
44
44
|
|
|
45
|
-
Keep these distinct, and never merge
|
|
45
|
+
Keep these distinct, and never merge any of them into one message.
|
|
46
46
|
|
|
47
47
|
| Condition | The voice it must throw |
|
|
48
48
|
| ------------------------------------------ | ---------------------------------------------------------------- |
|
|
@@ -51,8 +51,8 @@ Keep these distinct, and never merge two into one message.
|
|
|
51
51
|
| Several matches are reachable | `Interactive target "<name>" is ambiguous across <n> elements` |
|
|
52
52
|
| Still off-viewport after being scrolled to | `Interactive target "<name>" is unreachable after scrolling` |
|
|
53
53
|
|
|
54
|
-
- Report an absent control and a present-but-unreachable one as different findings:
|
|
55
|
-
a missing control,
|
|
54
|
+
- Report an absent control and a present-but-unreachable one as different findings: absence names
|
|
55
|
+
a missing control, and unreachability names the interface gating one that exists.
|
|
56
56
|
- Report ambiguity as a finding about the surface. Name the match count in the message, and
|
|
57
57
|
re-target the journey by role or region.
|
|
58
58
|
|
|
@@ -38,7 +38,7 @@ supposed to produce it. Source-reading review passes a component that renders no
|
|
|
38
38
|
Choose the smallest scope that satisfies the request:
|
|
39
39
|
|
|
40
40
|
- **Verdict:** one portfolio, one lane, no fixes.
|
|
41
|
-
- **Round:** portfolio →
|
|
41
|
+
- **Round:** portfolio → independent verdicts → reconciliation → fix units →
|
|
42
42
|
recapture.
|
|
43
43
|
- **Campaign:** rounds repeated until one terminal converged line, then independent gates.
|
|
44
44
|
|
|
@@ -53,8 +53,8 @@ confirmed finding in scope and rebuilding the harness gaps the verdicts expose.
|
|
|
53
53
|
2. **Seed candidates.** Turn your own mid-integration observations into numbered
|
|
54
54
|
confirm-or-refute candidates inside the verdict brief. Observations that stay in your
|
|
55
55
|
head are neither evidence nor findings.
|
|
56
|
-
3. **Take
|
|
57
|
-
|
|
56
|
+
3. **Take independent verdicts** on the SAME portfolio, in the fixed shape below. The
|
|
57
|
+
lanes are subjective design fit; objective state truth; and mechanical inventory of
|
|
58
58
|
copy, classes, icons, and accessibility attributes. This is the surface variant of the
|
|
59
59
|
adversarial pass in `.agents/orchestration.md`, so its rules bind: each lane is a fresh
|
|
60
60
|
subagent with a clean context, run in parallel, blind to the others until all have
|
|
@@ -18,9 +18,9 @@ Read `.agents/orchestration.md` first.
|
|
|
18
18
|
`.claude/agents/codex.md` owns the Sol transport contract in full — which work class uses MCP and
|
|
19
19
|
which uses the journaled CLI, the exact `codex exec` form, the journal and session-id discipline,
|
|
20
20
|
the recovery ladder, and the Windows notes. **Read it and follow it.** It is not restated here;
|
|
21
|
-
|
|
21
|
+
a restated transport contract drifts, and the copy you are not reading is the one that is right.
|
|
22
22
|
|
|
23
|
-
This role pins
|
|
23
|
+
This role pins what that file leaves to the dispatch: **the route is `analyst`, and its
|
|
24
24
|
sandbox is `read-only` in the current checkout.** Never widen it. An analyst unit that appears to
|
|
25
25
|
need a write is a misrouted unit — stop and report, do not switch routes.
|
|
26
26
|
|
|
@@ -11,8 +11,8 @@ You are the **Checker** — the mechanical conformance auditor in this project's
|
|
|
11
11
|
role set (see .agents/orchestration.md). You are exhaustive, evidence-first, and independent of
|
|
12
12
|
the builder. You are an Executor: do the audit yourself, spawn nothing.
|
|
13
13
|
|
|
14
|
-
Conformance review belongs to Grok first. You
|
|
15
|
-
ladder
|
|
14
|
+
Conformance review belongs to Grok first. You sit at the end of the tedious-work
|
|
15
|
+
ladder, after Grok and Luna on Codex, so a dispatch reaching you should
|
|
16
16
|
already record why the benches above it were unavailable.
|
|
17
17
|
|
|
18
18
|
## Job
|
|
@@ -24,9 +24,9 @@ CODEX_IMPLEMENTER_EFFORT=high
|
|
|
24
24
|
|
|
25
25
|
Raise the analyst to `xhigh` only for a stated hard reasoning need. Use `gpt-5.6-terra`
|
|
26
26
|
only for explicitly mechanical, taste-free roles. Use `gpt-5.6-luna` for absorption,
|
|
27
|
-
distillation, scouting, and bounded research when the Cursor bench is dark — it
|
|
28
|
-
|
|
29
|
-
models silently.
|
|
27
|
+
distillation, scouting, and bounded research when the Cursor bench is dark — it sits
|
|
28
|
+
between Cursor Grok and Sonnet on the tedious-work ladder, and the substitution is
|
|
29
|
+
recorded. Never switch models silently.
|
|
30
30
|
|
|
31
31
|
## Transport — pick by work class
|
|
32
32
|
|
|
@@ -43,7 +43,7 @@ models silently.
|
|
|
43
43
|
|
|
44
44
|
## Prepare the journaled CLI launch
|
|
45
45
|
|
|
46
|
-
Your
|
|
46
|
+
Your jobs are drafting the brief and running short MCP exchanges. For long work you
|
|
47
47
|
prepare the launch and return it; the Orchestrator runs it as a harness-tracked
|
|
48
48
|
background command under a hard cap.
|
|
49
49
|
|
|
@@ -52,7 +52,7 @@ never travel as shell arguments. Return the exact resolved command with a pointe
|
|
|
52
52
|
|
|
53
53
|
`timeout <cap> codex exec --json -C <working-directory> --sandbox <route-sandbox> --model gpt-5.6-sol -c "model_reasoning_effort=\"high\"" --output-last-message tmp/codex/<unit>-last.md "Read and execute the brief at tmp/codex/<unit>-brief.md exactly. Your final message must be the report it specifies." < /dev/null > tmp/codex/<unit>.jsonl`
|
|
54
54
|
|
|
55
|
-
- Return
|
|
55
|
+
- Return the brief path, that resolved command, and the journal path. Leave
|
|
56
56
|
`<cap>` unresolved — the Orchestrator owns it, per **Long-running commands → Launching**
|
|
57
57
|
in `.agents/orchestration.md`. You hold no record of prior runs.
|
|
58
58
|
- Never launch, background, poll, sleep-loop, restart, or kill an exec.
|