@orkestrel/scaffold 0.0.59 → 0.0.61

package/dist/host/agents/skills/orkestrel-prove-journey/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orkestrel-prove-journey
-description: Prove a browser application the way a person uses it — real keystrokes, clicks, and Tab/Enter against only what is visible and reachable — and generate the capture portfolio from those same journeys. Use when accepting a UI build, proving an application end to end, deciding whether a surface is reachable by keyboard alone, proving what a screen refuses as well as what it does, auditing whether the interface speaks the user's vocabulary rather than the engine's, producing the screenshots a design review judges, or whenever the only evidence a screen works is a test that drove it through JavaScript instead of through the interface.
+description: Prove a browser application the way a person uses it — real keystrokes, clicks, and Tab/Enter against only what is visible and reachable — through the journey layer @orkestrel/test/browser publishes, and generate the capture portfolio, the resolved-style matrix, and the statechart outcome from those same journeys. Use when accepting a UI build, proving an application end to end, deciding whether a surface is reachable by keyboard alone, proving what a screen refuses as well as what it does, proving the styles a browser actually resolved under each theme and viewport, driving a transition table through the interface and watching it run, auditing whether the interface speaks the user's vocabulary rather than the engine's, producing the screenshots a design review judges, routing a rendered question to an artifact a model can read, or whenever the only evidence a screen works is a test that drove it through JavaScript instead of through the interface.
 ---
 
 # Prove an application through human journeys
@@ -12,24 +12,63 @@ Read the current files in this order:
 1. `AGENTS.md`.
 2. `.claude/rules/tests.md` for test law, real implementations, and shared test infrastructure;
    `.claude/rules/browser.md` for browser and Vue usage; `.claude/rules/application.md` for app
-   composition and entries; `.claude/rules/documentation.md` for parity. Those rules are the
-   contract; this skill is the workflow.
-3. [layer.md](references/layer.md) before building, extending, or debugging the journey layer.
+   composition and entries; `.claude/rules/styles.md` for style centralization;
+   `.claude/rules/quality.md` for the instrument and negative-control law;
+   `.claude/rules/documentation.md` for parity. Those rules are the contract; this skill is the
+   workflow.
+3. [layer.md](references/layer.md) before importing, extending, or debugging the journey layer.
 4. [captures.md](references/captures.md) before registering a state or placing a capture.
-5. `guides/README.md`, the governing guide for the surface, and `ROADMAP.md` when present.
-6. The `*/types.ts` of every environment the journeys drive, plus the application's root component,
+5. [styles.md](references/styles.md) before asserting anything the browser resolved.
+6. [statechart.md](references/statechart.md) before declaring a transition or building the harness.
+7. [decide.md](references/decide.md) before routing a question to an instrument.
+8. `guides/README.md`, the governing guide for the surface, and `ROADMAP.md` when present.
+9. The `*/types.ts` of every environment the journeys drive, plus the application's root component,
    route entry, and store contract.
 
+## Declare the families
+
+Declare in the browser environment's `integration.test.ts` which families that surface carries, and
+assert in the always-on proofs that every declared family is present. A declaration names which
+families a surface owes. It never switches what a declared family proves.
+
+| Family     | Declared                                            | Proves                                                                 |
+| ---------- | --------------------------------------------------- | ---------------------------------------------------------------------- |
+| Journey    | Always                                              | Each user intent reaches its outcome through the interface             |
+| Refusal    | Always                                              | Each control the surface withholds, through one exact failure voice    |
+| Matrix     | Where the surface ships more than one variant       | The values the browser resolved under each declared variant            |
+| Statechart | Where a journey drives a control that carries state | Each declared transition, driven through the interface where it can be |
+| Transport  | Where the surface persists or restarts              | Persistence, restart, and storage failure through real implementations |
+| Capture    | Under the capture flag                              | The registry times the variants, each registered file written to disk  |
+
+- Refuse a declaration that omits a family whose trigger the surface meets. Report the omission as a
+  scope finding and stop; never prove the remaining families around it.
+- Assert the declaration itself: a family listed with no proof, and a proof belonging to no listed
+  family, each fail the run.
+
+## Read the variant once
+
+Read one `variant` value at run start, and let it choose the capture destination, the matrix row,
+and the statechart run together. Never split the theme from the viewport; a split writes a filename
+naming a combination the run did not render.
+
+- Declare every variant once as a published `CaptureVariant` — its `name`, its `width`, its
+  `height`, and the `apply` that switches the theme — and read that list from the capture family and
+  the matrix family alike.
+- Loop every declared variant inside one run for the matrix family
+  ([styles.md](references/styles.md) → Run per variant).
+- Render exactly one variant per run for the capture family
+  ([captures.md](references/captures.md) → Variants).
+
 ## Apply the journey laws
 
-1. **Drive only what a person can see and reach.** Target every control by its ARIA role and its
-   accessible name as rendered. Never reach into a component instance, a store, a transport, a
-   copied credential, or a test-only hook to make a step succeed. Report a step that cannot be
-   performed through the interface as a finding about the interface.
+1. **Drive only what a person can see and reach.** Resolve every interactive target by its ARIA
+   role and its accessible name as rendered. Never reach into a component instance, a store, a
+   transport, a copied credential, or a test-only hook to make a step succeed. Report a step that
+   cannot be performed through the interface as a finding about the interface.
 2. **Assert what is seen.** Quote the rendered text a person reads, which is `innerText` — a label
-   under `text-uppercase` asserts as `TRACE` where the source says `Trace`. Never let a state read
-   replace a perception assertion; it may only corroborate one, and `.claude/rules/tests.md` fixes
-   which state a test may read at all.
+   under `text-uppercase` asserts as `TRACE` where the source says `Trace`. Never let an entity
+   state read replace a perception assertion; it may only corroborate one, and
+   `.claude/rules/tests.md` fixes which entity state a test may read at all.
 3. **Assert what the interface withholds.** Assert every refusal through the resolver's exact
    failure voice, and distinguish an absent control from a present but humanly unreachable one.
 4. **Keep transport and persistence proofs in their own declared block,** never inside a journey.
@@ -43,17 +82,17 @@ Read the current files in this order:
 7. **Type only what a person would.** Journeys carry trusted input; adversarial payloads belong to
    the transport family and the parser suites.
 
-## Build or verify the journey layer
-
-- Build the layer as shared browser test infrastructure under `.claude/rules/tests.md`: it lives in
-  the workspace's browser test setup module, exports every helper from there, and adds a journey
-  helper only where `@orkestrel/test` publishes none. Never declare a resolver inside a test file.
-- Give the layer every capability [layer.md](references/layer.md) fixes: the role-scoped resolver
-  and its distinct failure voices, region-scoped resolution, the input and traversal verbs, the
-  perception readers, and the capture hook.
-- Drive every step through the browser provider's user-event API, and never dispatch a constructed
-  event ([layer.md](references/layer.md) → What it drives).
-- Re-verify the layer against what the application renders now whenever markup changes
+## Import the journey layer
+
+- Import every journey verb, reader, and fixture builder from `@orkestrel/test/browser`. Write one
+  of your own only where that package publishes none for the act
+  ([layer.md](references/layer.md) → Import, never implement).
+- Place a helper you must write in the workspace's browser test setup module, name it for the act,
+  and export it from there under `.claude/rules/tests.md`. Never declare a resolver inside a test
+  file.
+- Drive every step through the published verbs, and never dispatch a constructed event
+  ([layer.md](references/layer.md) → What it drives).
+- Re-verify every target against what the application renders now whenever markup changes
   ([layer.md](references/layer.md) → Role vocabulary).
 
 ## Derive journeys from intents
@@ -86,7 +125,7 @@ placement and scope `.claude/rules/tests.md` fixes.
 - Give every surface a refusal family: the controls a person must not reach in the state the
   journey has put the surface in.
 - Assert the exact failure voice the case means. Never write an assertion that accepts more than
-  one voice.
+  one voice ([layer.md](references/layer.md) → The failure voices).
 - Cover the restrictions the interface imposes on itself: a collapsed panel's field, a verb
   belonging to another kind of object, a control disabled until its precondition lands.
 - When a refusal changes voice after a markup change, read it as a role or reachability change
@@ -103,17 +142,34 @@ placement and scope `.claude/rules/tests.md` fixes.
   that clears it.
 - Assert restart by starting a second session over the same store and polling the restored value.
 
+## Prove the styles
+
+Follow [styles.md](references/styles.md) for the resolved-value law, the per-variant run, the
+composited contrast reading and its under-bar negative control, the authored-class census, the
+`extractStyles` reading, and the token comparison.
+
+## Prove the statechart
+
+Follow [statechart.md](references/statechart.md) for the transition table, the scenario per
+transition, the runner, the harness a person watches, and the gate that drives the harness through
+the interface.
+
 ## Generate the portfolio
 
 Follow [captures.md](references/captures.md) for the state registry and its placement rules, the
 theme-and-viewport variant matrix, the always-on filename proof, the capture-run membership proof,
 and how a state that exists only during an activation is captured.
 
-When a capture and a green suite disagree, the capture is the evidence and the fixture is the
+Where a capture and a green suite disagree, take the capture as the evidence and the fixture as the
 defect.
 
 Route review of the portfolio to the `orkestrel-polish-surface` campaign. Do not judge it here.
 
+## Route the question
+
+Follow [decide.md](references/decide.md) before spending a round on a question. It fixes which
+instrument judges which claim, what `prove` cannot serve, and what the run's written artifact holds.
+
 ## Accept
 
 Completion requires all of:
@@ -123,10 +179,18 @@ Completion requires all of:
 - keyboard-only reachability proven on every surface the journeys cover;
 - a refusal family per surface, each asserting one exact failure voice;
 - the transport family declared separately, driven through real implementations, and convergent;
+- the declared families each proven, and the declaration itself asserted;
+- the matrix family read once per declared variant, each style instrument carrying the negative
+  control that must read under its bar in the same run;
+- the authored-class census and the `extractStyles` reading taken on the mounted surface, each
+  reporting the population it walked;
+- the statechart table driven to a terminal outcome with no failed row, and the harness gate green;
 - the registry-times-variants filename proof and the state-placement proof green in an ordinary run;
-- one capture run per variant writing every registered file, each read back non-empty;
+- one capture run per variant writing every registered file, and the disk-membership proof green;
+- the written artifact produced for every variant the run rendered, named by that variant;
 - perception assertions quoting rendered text, and the vocabulary sweep green on the whole page;
 - the repository gates green, under the independent-verification law in `.agents/orchestration.md`.
 
-Report each journey by the intent it proves, the refusals it establishes, the states it placed, and
-every surface finding the layer's refusals exposed.
+Report each journey by the intent it proves, the refusals it establishes, the states it placed, the
+variants it read, the statechart outcome it reached, and every surface finding the layer's refusals
+exposed.

package/dist/host/agents/skills/orkestrel-prove-journey/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: 'Prove Human Journeys'
   short_description: 'Prove an application through the interface a person uses'
-  default_prompt: 'Use $orkestrel-prove-journey to prove this application through the interface a person uses, and generate the capture portfolio from those journeys.'
+  default_prompt: 'Use $orkestrel-prove-journey to prove this application through the interface a person uses, and generate the capture portfolio, the resolved-style matrix, and the statechart outcome from those journeys.'

package/dist/host/agents/skills/orkestrel-prove-journey/references/captures.md

@@ -4,64 +4,88 @@ Take every screenshot from an acceptance journey, at the moment that journey is
 picture names. Never add a test whose only purpose is a screenshot, and never stage a state for the
 camera that a journey did not reach through the interface.
 
-## The capture hook
-
-```ts
-capture(state: string): Promise<string | undefined>
-```
-
-- Return `undefined` and do nothing when the capture flag is unset, so an ordinary run neither
-  resizes the viewport nor writes a file.
-- Read one variant value that names the theme and the viewport together, and refuse a value that
-  names no registered variant.
-- Apply that variant's theme and viewport inside the hook, so the run's single variant value is the
-  only source of both.
-- Write one file named `<state>--<variant>.png` under the workspace's git-ignored `tmp/` tree, and
-  return the path it wrote.
+## The hook
+
+`createPortfolio(options)` is the capture door, and `place(state, element?)` is the hook. Build the
+portfolio once per file from a `PortfolioOptions` value carrying the registry as `states`, every
+declared `CaptureVariant` as `variants`, this run's `variant`, the `directory` each file is written
+to, and the flag as `enabled`.
+
+- Place a state with `place(state)` for the whole page, and `place(state, element)` where the
+  picture is one element.
+- Leave `enabled` unset in an ordinary run. `place` then returns `undefined`, resizes nothing,
+  writes nothing, and records nothing.
+- Read `files` for the registry expanded across every variant, `placements` for what this run placed,
+  and `paths` for what it wrote. Each hands back a snapshot.
+
+The package already refuses these, so assert none of them again:
+
+| Refusal                                                              | Raised by             |
+| -------------------------------------------------------------------- | --------------------- |
+| `Capture variant "<name>" is not registered`                         | `createPortfolio`     |
+| `Capture state "<state>" is not registered`                          | `place`, when enabled |
+| `Capture state "<state>" is already placed`                          | `place`, when enabled |
+| `Capture frame at <path> is not the one this run shot`               | `captureFrame`        |
+| `Capture frame was written to <written> where <asked> was asked for` | `captureFrame`        |
 
 ## The registry
 
-Declare a frozen list of state names and a frozen list of variants in the journey file.
+Declare the state names and the variants once in the journey file, and build the portfolio from
+that declaration.
 
 - Name a state for its surface and its condition — `answer-partial`, `start-storage-failure`,
   `case-delete-confirmation`.
 - Register the states the design work actually needs, and place every registered one. Never leave a
   registered state unplaced.
-- Wrap the hook in a placement helper that refuses an unregistered state name, refuses a second
-  placement of the same state, records each written path, and refuses a filename written twice.
-- Place a state from inside the journey that reaches it, immediately after the assertion that
-  proves the surface is in that state.
+- Place a capture state from inside the journey that reaches it, immediately after the assertion
+  that proves the surface is in the condition that state names.
+- Record each placed name in the suite's own set in the same step that calls `place`. That set, not
+  `placements`, is what the always-on placement proof reads.
 
 ## Variants
 
-- Name a variant as one value carrying both the theme and the viewport, such as `dark-390`. Never
-  split them into separate selectors: a split lets a run write a filename describing a combination it
-  did not render.
-- Render one variant per run, and produce the portfolio — the registry times the variants — by
-  repeating the run once per variant.
+The run axis is fixed in [SKILL.md](../SKILL.md) → Read the variant once, and the theme switch each
+variant's `apply` performs is fixed in [styles.md](styles.md) → Run per variant. The capture family
+adds these.
+
+- Produce the portfolio — the registry times the variants — by repeating the run once per variant.
+- Name each variant for the theme and the viewport it renders, such as `dark-390`. The name is the
+  second half of every filename the run writes, so a variant named for one alone produces a
+  portfolio nobody can tell apart.
+- Pass the whole variant list as `variants` and this run's name as `variant`. `createPortfolio`
+  refuses a `variant` no declared variant carries, and `files` expands the registry across the whole
+  list rather than across the one being rendered.
+
+## The proofs the suite owes
 
-## The proofs
+The package times the registry and refuses a bad placement. It asserts nothing about either, so the
+suite carries these.
 
-| Proof                | Runs                        | Asserts                                                                                        |
-| -------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- |
-| Filename expansion   | Always                      | The registry's length and uniqueness, the variant count, and that the expansion is unique      |
-| Portfolio membership | Always; disk under the flag | Every registered state was placed; under the flag, the files on disk are exactly the expansion |
+| Proof                | Runs           | Asserts                                                                            |
+| -------------------- | -------------- | ---------------------------------------------------------------------------------- |
+| Filename expansion   | Always         | `expandCaptures(states, variants)` has one entry per state and variant, all unique |
+| Placement membership | Always         | The suite's placed set equals the registry, as sets                                |
+| Disk membership      | Under the flag | The filenames on disk equal the expansion for this run's variant                   |
 
 - Keep the filename proof always-on, so a registry edit that introduces a duplicate or a collision
-  fails the ordinary run.
-- Assert placement equality as set equality against the registry, in every run. Never assert a
-  count: a count passes while one state is placed twice and another never.
-- Under the capture flag, assert the written filenames equal the registry expanded for the run's
-  variant, then read each file back and require non-empty contents. Never treat the path a
-  screenshot call returned as proof that a file exists.
+  fails the ordinary run. Compare `expandCaptures(states, variants)` against `files` and against a
+  set built from it; a length equal to the set's size is what proves the expansion unique.
+- Assert placement as set equality against the registry, in every run. Never assert a count: a count
+  passes while one state is placed twice and another never.
+- Read the placement proof from the suite's own set rather than from `placements`. An ordinary run's
+  `place` returns before it reads the registry, so `placements` is empty there and an unregistered name
+  reaches no refusal until a capture run. The always-on placement proof is what catches it.
+- Under the flag, assert the written filenames equal the registry expanded for the run's variant.
+  `captureFrame` already reads each file back and compares its bytes against the frame it shot, so
+  the path `place` returns is proof the file exists and holds that frame.
 - Put the membership proof last in the file, after every journey that feeds its tally.
 
 ## Transient states
 
-Capture a state that exists only while an activation is in flight from inside that activation,
-never after the click returns.
+Capture a state that exists only while an activation is in flight from inside that activation, never
+after the click returns.
 
-- Attach a one-shot listener to the resolved control, place the capture from inside it, then click
+- Attach a one-shot listener to the resolved control, call `place` from inside it, then click
   through the normal verb and await the promise the listener recorded.
 - Fail the step when the listener never ran.
 

package/dist/host/agents/skills/orkestrel-prove-journey/references/decide.md

@@ -0,0 +1,68 @@
+# Routing a question
+
+Route a question by what judges the claim, before spending a round on it. Report a question no
+instrument here answers as open, and never answer it with the nearest instrument instead.
+
+| The claim is judged by                 | Route it to                                  |
+| -------------------------------------- | -------------------------------------------- |
+| A compiler, a linter, or a Node runner | The `prove` tool, with its negative control  |
+| A person's eye                         | The run's written artifact, named by variant |
+| A person watching a widget move        | A statechart harness deep link               |
+| The browser's own resolved value       | The matrix family ([styles.md](styles.md))   |
+
+Never ask `prove` about pixels, and never ask a screenshot about types.
+
+## The receipt half
+
+A claim a compiler, a linter, or a Node runner judges goes to `prove`. Supply its workspace project,
+its case, its negative control, and the stage that negative control must break at.
+`.claude/rules/quality.md` § Instruments owns that rule and the receipt line every report quotes;
+follow it there rather than restating it here.
+
+- Route the control-to-affordance table, the declared class allowlist's own declaration, the variant
+  expansion, and the glyph registry here. Each supplies a project, a case, and a negative control.
+- Read a `no receipt` line as the claim unproved, and report the stage that refused.
+
+## The limit that decides the split
+
+`prove` cannot serve a browser project in `@orkestrel/probe` 0.0.11. The following refusals are each
+reproduced:
+
+- The runtime stage looks a project up by the name it infers, and a browser project is instantiated
+  under its browser-expanded name, so the lookup finds nothing and the claim is refused as missing.
+- The runtime stage pins the `threads` pool, so a browser project's specification runs in a Node
+  worker. `@orkestrel/test/browser` imports `vitest/browser` at module scope, so the browser setup
+  file throws before the case runs and the failure reads as the claim's.
+
+Never route a rendered question to `prove` while that holds. The pinned-pool refusal arrives as a
+case failure, which reads exactly like a broken claim.
+
+## The rendered artifact
+
+Write one text file per variant under the workspace's git-ignored `tmp/` tree, named for the variant,
+so a decision cites the exact file and reads it in one call.
+
+Compose each file from what the run already holds:
+
+- `describeTree` of the mounted surface, for the roles, names, and states a person meets.
+- `describeFocus` of the mounted surface, for the focus order the keyboard walk took.
+- The resolved-style rows the matrix family read for that variant — the property, the element, and
+  the value the browser returned.
+- The journal's `steps` and `output`, for what the run did and what the page said while it did it.
+- The capture filenames this run wrote, so the artifact and the portfolio name the same states.
+
+Rules the artifact obeys:
+
+- Name each file for the variant that produced it. An artifact that names no variant describes a
+  combination nobody can reproduce.
+- Write one file per variant, never one file per journey. A decision is taken per variant, and a
+  reader opening one file per journey pays a round trip per journey.
+- Regenerate the whole set after any surface change. Never judge a round against a set that is part
+  old and part new.
+- Keep it out of version control.
+
+## The harness link
+
+Send a look a person decides on to a statechart harness deep link rather than to a file. Name the
+exact link in the round, and let the person watch the widget move rather than read a still of it
+([statechart.md](statechart.md) → Build the harness a person watches).