@orkestrel/scaffold 0.0.33 → 0.0.36

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

@@ -0,0 +1,124 @@
+---
+name: orkestrel-human-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.
+---
+
+# Prove an application through human journeys
+
+## Load authority
+
+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.
+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,
+   route entry, and store contract.
+
+## 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.
+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.
+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.
+   Assert every live or asynchronous fact by convergence — poll until it contains or equals — never
+   by an identity read of one frame.
+5. **Generate the portfolio from the acceptance journeys.** Place each registered state inside the
+   journey that reaches it, and never register a state no journey reaches.
+6. **Commit a value through an act a person performs:** Enter, Tab away, or a named button. Report a
+   surface that commits on a timer, on an unpredictable event, or only after work the person cannot
+   observe as a surface finding, and never work around it in the layer.
+
+## 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
+  ([layer.md](references/layer.md) → Role vocabulary).
+
+## Derive journeys from intents
+
+Write one journey per user intent, named for what the person achieves rather than for the
+components it passes through. Place them in the browser environment's `integration.test.ts`, whose
+placement and scope `.claude/rules/tests.md` fixes.
+
+- Enter through the real entry: mount the shipped root component with a real store and the route a
+  person lands on, and let the application load itself.
+- Reach each surface's own controls through forward Tab traversal in at least one journey.
+- Type keystroke by keystroke where the keystrokes are the subject; fill in one operation where the
+  text is only a payload the person pastes.
+- Poll every fact the application produces asynchronously until it converges. Never assert one from
+  a single read after the action.
+- Assert the negative beside the positive whenever a value replaces another: the new sentence is
+  present **and** the old one is gone.
+- After a confirmed destructive action, assert through trusted input that focus landed on a visible,
+  announced location.
+- Assert the whole page's perception never matches the vocabulary the product does not speak —
+  engine, schema, and implementation words the interface is supposed to translate.
+- Report a bare accessible name that answers for two reachable elements on one screen as a surface
+  finding, and target through role or region until the surface is fixed.
+
+## Prove the refusals
+
+- 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 either of
+  two 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
+  before treating the element as missing
+  ([layer.md](references/layer.md) → Role vocabulary).
+
+## Declare the transport family
+
+- Name the block for what it proves — persistence, restart, storage failure.
+- Drive it through the application's real session and store contracts. Build a store that stalls a
+  read, fails a fixed number of reads, or fails a write as an inert configurable implementation of
+  the published interface, under the real-implementation law in `AGENTS.md`.
+- Prove the visible half in a journey: the failure sentence a person reads, and the retry control
+  that clears it.
+- Assert restart by starting a second session over the same store and polling the restored value.
+
+## 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.
+
+Route review of the portfolio to the `orkestrel-polish-surface` campaign. Do not judge it here.
+
+## Accept
+
+Completion requires all of:
+
+- every in-scope user intent reaching its outcome through the interface, with no step that reaches
+  past it;
+- 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 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;
+- 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.

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

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

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

@@ -0,0 +1,74 @@
+# The capture portfolio
+
+Take every screenshot from an acceptance journey, at the moment that journey is in the state the
+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 registry
+
+Declare two frozen lists in the journey file: the state names, and the variants.
+
+- 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.
+
+## Variants
+
+- Name a variant as one value carrying both the theme and the viewport, such as `dark-390`. Never
+  split them into two 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 two proofs
+
+| 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 |
+
+- 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.
+- 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.
+
+- Attach a one-shot listener to the resolved control, place the capture from inside it, then click
+  through the normal verb and await the promise the listener recorded.
+- Fail the step when the listener never ran.
+
+## Hygiene
+
+- Keep the portfolio out of version control.
+- Regenerate the whole matrix from the journeys after any surface change. Never judge a round
+  against a portfolio that is part old and part new.
+- Route review of the portfolio to the `orkestrel-polish-surface` campaign, which owns preflight,
+  verdicts, and reconciliation. This reference owns only how the journeys generate it.

package/dist/host/agents/skills/orkestrel-human-journey/references/layer.md

@@ -0,0 +1,131 @@
+# The journey layer
+
+Build every capability here before writing the first journey, and route every journey step through
+it. Treat a journey that works around a missing capability as a layer defect.
+
+Implement the signatures below as a contract in the workspace's browser test setup module; never
+copy them as source. Name each helper for the human act it performs.
+
+## What it drives
+
+- Drive the real browser through the installed Vitest browser provider. Import its `page` locators
+  and `userEvent` from `vitest/browser`; the `@vitest/browser/context` specifier is deprecated and
+  is not the import a new layer uses.
+- Use the provider verbs for input: `click`, `keyboard`, `tab`, `type`, `clear`, `fill`, and
+  `selectOptions`. Use `page.viewport` and `page.screenshot` for captures, and the runner's file
+  command to read a written capture back.
+- Never dispatch a constructed event from the layer or from a journey. The centralized event
+  factories `.claude/rules/tests.md` prescribes serve unit tests whose subject is the handler; a
+  journey drives input through the provider verbs only.
+- Never let a helper take an element, a component instance, or a selector from the caller. Every
+  helper resolves its own target from role and accessible name.
+
+## The resolver
+
+```ts
+resolveAccessible(name: string): HTMLElement
+resolveAccessible(role: string, name: string): HTMLElement
+```
+
+- Match the accessible name exactly, never a substring.
+- Search a fixed set of interactive roles for the bare-name form, and exactly the named role for
+  the two-argument form.
+- Count a match as reachable only when every condition holds: it is connected; it passes a
+  visibility check that honours opacity and CSS; its box has non-zero width and height; its
+  `tabIndex` is at least zero; it matches neither `:disabled` nor `[aria-disabled="true"]`; and it
+  has no `[inert]` ancestor.
+- Scroll a wholly off-viewport target into view once, then measure reachability again. Count a
+  control a person can scroll to as reachable, and one that stays outside the viewport as
+  unreachable.
+- Give the layer a rendered-only resolver beneath the public one, and use it from the acting verbs
+  so a click does not fail on a target the act itself scrolls into view.
+
+### The failure voices
+
+Keep these distinct, and never merge two into one message.
+
+| Condition                                  | The voice it must throw                                          |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| No element carries the name                | `No interactive element has the accessible name "<name>"`        |
+| Every match fails a reachability condition | `Interactive target "<name>" is not visible and focus-reachable` |
+| Several matches are reachable              | `Interactive target "<name>" is ambiguous across <n> elements`   |
+| Still off-viewport after being scrolled to | `Interactive target "<name>" is unreachable after scrolling`     |
+
+- Report an absent control and a present-but-unreachable one as different findings: the first names
+  a missing control, the second names the interface gating one that exists.
+- Report ambiguity as a finding about the surface. Name the match count in the message, and
+  re-target the journey by role or region.
+
+## Role vocabulary
+
+Never infer a role from markup. Confirm the computed role in the browser whenever a target stops
+resolving.
+
+- A `list`-bearing input computes `combobox`, not `textbox`. Attaching native suggestion machinery
+  to a field is a role change: re-target every journey that names that field, and read a resolver
+  miss immediately after such a change as this before treating the element as missing.
+- Always target a tab by its role. A tab and its panel collide on a bare name by construction,
+  because the panel is labelled by its tab.
+- `<summary>` is exposed as a native disclosure rather than through a role the provider's role
+  locators accept. Give the layer a separate disclosure verb keyed to the summary's rendered text,
+  applying the same reachability conditions and its own failure voices.
+
+## Region-scoped resolution
+
+```ts
+clickAccessibleWithin(region: string, role: string, name: string): Promise<void>
+```
+
+- Provide this form for repeated short verbs such as `Add`, and for a control whose accessible name
+  is completed by a status the row renders.
+- Apply the same reachability conditions inside the region, and throw voices that name the region
+  as well as the target.
+
+## Input and traversal
+
+| Verb                         | Contract                                                                                                      |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `typeAccessible(name, text)` | Focus the field, select all, delete, then send real keystrokes. Escape the provider's key syntax in the text. |
+| `fillAccessible(name, text)` | Replace the value in one operation for text too long to type. The real element still publishes real input.    |
+| `pressKeys(keys)`            | Send a provider keyboard sequence for Enter, arrows, modifiers, and combinations.                             |
+| `traverseAccessible(name)`   | Move focus by forward Tab from wherever focus is, and return the target once focus lands on it.               |
+
+- Count a traversal step only when focus actually lands on an element, and never charge the step
+  bound for a Tab that moved nothing.
+- End the traversal when focus revisits an element, which is one complete cycle of the tab order,
+  and throw the traversal's own voice, carrying the trail of what focus did reach. Keep a hard cap
+  above the cycle so a page with no tab order fails instead of hanging.
+- Re-resolve the target by role and name on every step, and never hold a node reference across
+  steps. A framework may replace the node between resolution and focus arrival.
+- Never call the browser's focus method to place focus.
+
+## Perception
+
+```ts
+readPerception(name: string): string
+```
+
+- Return the normalized `innerText` of exactly one visible named region, dialog, table, tab panel,
+  alert, or status. Collapse whitespace runs to single spaces and trim.
+- Read `innerText`, never `textContent`: `innerText` applies CSS transforms and leaves out content
+  the layout hides. Quote that text in assertions.
+- Include descendant visually-hidden text, which a screen reader perceives and which a clip-based
+  hiding technique leaves in `innerText`.
+- Throw when the named region is absent, hidden, or ambiguous.
+- Give the layer a whole-page perception reader for cross-region sentences and the vocabulary
+  sweep, a focus reader that returns the active element's rendered text, and a value reader that
+  returns a resolved control's value. A perception assertion may quote that value: it is a rendered
+  fact rather than internal state.
+
+## Mounting and cleanup
+
+- Mount the shipped root component with its real provisions and return an idempotent cleanup that
+  unmounts the app and removes its container.
+- Undo everything a journey changed after each test: unmount, destroy the session, reset the theme,
+  clear the keys the application persisted, and return the route to its entry. Never let a journey
+  inherit the previous journey's state.
+
+## The capture hook
+
+Give the layer exactly one capture helper. [captures.md](captures.md) owns the registry, the
+variant matrix, and the proofs that read what it wrote.

package/dist/host/claude/agents/analyst.md

@@ -43,9 +43,9 @@ Everything `.agents/orchestration.md`'s dispatch contract requires, plus:
 
 An audit or analysis unit is long work. **Do not launch it.** Draft the brief to
 `tmp/codex/<unit>-brief.md`, resolve the command per `codex.md`, and return the brief path, the
-exact resolved command, the journal path, and a cap recommendation. The Orchestrator launches it as
-a tracked background command under a hard cap, so the harness owns the lifecycle and a wedged bench
-dies loudly instead of silently. Never detach a run, poll, restart, or kill one.
+exact resolved command, and the journal path. The Orchestrator launches it as a tracked background
+command and owns the cap: it holds the record of prior runs, and you do not. Never detach a run,
+poll, restart, or kill one.
 
 A short bounded question on a live thread may use the MCP tools directly, per `codex.md`'s
 work-class rule. Persist the thread id the moment a response carries it.
@@ -53,7 +53,7 @@ work-class rule. Persist the thread id the moment a response carries it.
 ## Return
 
 The brief path, the resolved command, the journal path, the session id, and — once the Orchestrator
-reports the exec complete — Sol's answer verbatim, labelled untrusted and unaccepted.
+reports the exec complete — Sol's answer verbatim, labelled untrusted and unaccepted. Never a cap.
 
 Never edit, implement, reconcile, accept, commit, push, install, read a credential, or spawn any
 agent.

package/dist/host/claude/agents/codex.md

@@ -1,6 +1,6 @@
 ---
 name: codex
-description: 'GPT-5.6 Sol transport contract and the implementer route: writes one bounded unit in the main checkout as the sole serial writer. The analyst route has its own named role in `analyst`; this file remains the transport contract both routes follow. Never accepts its own output.'
+description: 'The GPT-5.6 Sol transport contract every Claude-side bridge follows: work class to transport, the exact exec form, journalling, session ids, and recovery. Reach a route by its own name — `analyst` for audit, `sol` for implementation. Never dispatched directly for work.'
 tools: Bash, Read, Grep, Glob, mcp__codex__codex, mcp__codex__codex-reply
 model: sonnet
 effort: low
@@ -52,9 +52,9 @@ never travel as shell arguments. Return the exact resolved command with a pointe
 
 `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`
 
-- Return four things: the brief path, that resolved command, the journal path, and a cap
-  recommendation with its basis — the observed duration high mark for this work class,
-  plus an independently budgeted gate allowance, plus explicit slack.
+- Return three things: the brief path, that resolved command, and the journal path. Leave
+  `<cap>` unresolved — the Orchestrator owns it, per **Long-running commands → Launching**
+  in `.agents/orchestration.md`. You hold no record of prior runs.
 - Never launch, background, poll, sleep-loop, restart, or kill an exec.
 - Keep `< /dev/null`. A background-launched exec that inherits an open stdin pipe wedges
   before its first event, and only the cap ever surfaces it.

package/dist/host/claude/agents/grok.md

@@ -54,10 +54,10 @@ Write that chain to `tmp/cursor/run.sh` and run the file, so the resolution, the
 journalling are one artifact the next run reuses.
 
 Run that yourself only for a short bounded ask finishing in about two minutes. For anything
-longer your job ends at drafting: return the brief path, the exact resolved command, the
-journal path, and a cap recommendation — the observed duration high mark plus explicit
-slack — and let the Orchestrator launch it as a harness-tracked background command. Never
-detach a run and end your turn; an unowned run has no completion signal and no death notice.
+longer your job ends at drafting: return the brief path, the exact resolved command, and the
+journal path, and let the Orchestrator launch it as a harness-tracked background command under
+a cap it owns. Never recommend a cap — you hold no record of prior runs. Never detach a run and
+end your turn; an unowned run has no completion signal and no death notice.
 
 ## Brief and containment
 

package/dist/host/claude/agents/sol.md

@@ -0,0 +1,56 @@
+---
+name: sol
+description: 'GPT-5.6 Sol implementation of one bounded nontrivial unit, reached by name rather than by a remembered route. The objective mirror of the Opus `implementer`; favours constraint-heavy, mechanical-precision units. Never accepts its own output.'
+tools: Bash, Read, Grep, Glob, mcp__codex__codex, mcp__codex__codex-reply
+model: sonnet
+effort: low
+permissionMode: default
+---
+
+You are the named Claude-side bridge to the Sol `implementer`. You are a cheap driver: you prepare
+a dispatch and return what Sol said, labelled untrusted. You never implement, judge, reconcile, or
+endorse the result yourself.
+
+Read `.agents/orchestration.md` first.
+
+## Transport, sandbox, journalling, recovery
+
+`.claude/agents/codex.md` owns the Sol transport contract in full — work class to transport, the
+exact `codex exec` form, the journal and session-id discipline, the recovery ladder, and the
+Windows notes. **Read it and follow it.** It is not restated here; two copies of a transport
+contract drift, and the one you are not reading is the one that is right.
+
+This role pins the one thing that file leaves to the dispatch: **the route is `implementer`, and
+its sandbox is `workspace-write`.** A unit that needs no write is a misrouted unit — stop and
+report, do not switch routes.
+
+## What the brief must contain
+
+Everything `.agents/orchestration.md`'s dispatch contract requires, plus:
+
+- Owned files, shared and off-limits files, and the acceptance criteria that close using owned
+  files alone.
+- The `AGENTS.md` non-negotiables, the applicable rules, and the governing guide or spec. An
+  external delegate carries no exemption.
+- **Every authority the brief references must exist in the tree the exec is rooted in.** Check
+  before dispatch. A brief citing a file the executor cannot find delivers nothing while looking
+  like authority, and it fails silently.
+- The deviation contract, scoped: a conflict with the primary objective stops the unit; an
+  ancillary conflict is the executor's to decide, record, and carry on from.
+
+## Launching
+
+An implementation unit is long work. **Do not launch it.** Draft the brief to
+`tmp/codex/<unit>-brief.md`, resolve the command per `codex.md`, and return the brief path, the
+exact resolved command, and the journal path. The Orchestrator launches it as a tracked background
+command and owns the cap: it holds the record of prior runs, and you do not. Never detach a run,
+poll, restart, or kill one.
+
+Writing units are strictly serialized. Never run beside another writer in the same checkout.
+
+## Return
+
+The brief path, the resolved command, the journal path, the session id, and — once the Orchestrator
+reports the exec complete — Sol's answer verbatim, labelled untrusted and unaccepted. Never a cap.
+
+Never edit, judge, reconcile, accept, commit, push, install, read a credential, or spawn any agent.

package/dist/host/claude/rules/application.md

@@ -48,9 +48,11 @@ paths:
 - Give app/server process signals to a tested, explicitly stoppable,
   generation-safe runner whose stale failures cannot release a newer run.
 - Return the runner from convenience startup, so normal cleanup cannot be hidden.
-- `ApplicationServerRunner` lives alone in `ApplicationServerRunner.ts`. The
-  `startApplicationServer` convenience factory belongs in `factories.ts`. `main.ts`
-  invokes it and owns no reusable declarations or duplicated signal handling.
+- `ApplicationServerRunner` lives alone in `ApplicationServerRunner.ts`.
+  `startApplicationServer` belongs in `handlers.ts` beside the other process-lifecycle
+  functions, because `factories.ts` admits only `create`-prefixed construction and this
+  one starts a signal-owning resource. `main.ts` invokes it and owns no reusable
+  declarations or duplicated signal handling.
 - Do not add showcase, auth, storage, proxy, CSS framework, or other product
   policy unless the request requires it.
 - Test repeated lifecycle, concurrent calls, malformed environment input,

package/dist/host/claude/rules/documentation.md

@@ -22,7 +22,7 @@ Documentation is an enforced contract, not explanatory decoration. The Writing r
 - Read the matching spec/guide before code, form the intended design, then compare implementation. Existing code is a verification target, not ground truth.
 - `AGENTS.md` and its linked rules are the sole convention source. Do not create competing instruction copies in guides.
 - `guides/README.md` is the map: maintain both a concept index and a directory index. The concept index runs `spec ↔ source ↔ tests ↔ showcase` minus every column whose subject this workspace lacks, so an app-only workspace that publishes no library and builds no showcase still owes a full index over the columns it has.
-- `ROADMAP.md` is the sequenced plan of record. Each chunk reaches green before the next.
+- Where the repository keeps one, `ROADMAP.md` is the sequenced plan of record. Each chunk reaches green before the next.
 - A showcase is executable proof of public API. A missing demonstration is a missing feature, detectable by parity.
 - An integration surface's guide documents the validated hookup for each supported client: the exact commands run, the authentication and approval model that client needs, and the honest limit wherever a client cannot reach part of the surface.
 
@@ -33,7 +33,7 @@ Documentation is an enforced contract, not explanatory decoration. The Writing r
 - TypeScript, SCSS, Markdown, tests, and showcase remain aligned.
 - A parity failure identifies drift; never suppress or weaken the test.
 - A vendored dependency guide is a mirror. Its relative links address the upstream tree and resolve to nothing here, so they are outside local-link parity. Refresh a mirror rather than rewriting it: a rewritten copy is a translation, and no comparison against the fetched bytes can check it.
-- Falsify a prose claim the way you falsify a code claim. The parity test proves a name exists, never that a sentence about behavior is true, so run the example and read what it returns. A `// false` beside a call that returns `true` is a defect of the same kind as a wrong return value, and it reaches every consumer who installs the package.
+- Falsify a prose claim the way you falsify a code claim. The parity test proves a name exists, never that a sentence about behavior is true, so run the example and read what it returns. A `// false` beside a call that returns `true` is a defect of the same kind as a wrong return value, and it reaches every consumer who installs the package. That proof has a home: `tests/guides.test.ts` executes the flagship fences, per `.claude/rules/tests.md`. An ordered behaviour with no gate is not a gate.
 - Re-read the prose last, against what actually shipped. Where a change chose to document a limit rather than close it, the sentence was often drafted for the option that lost, or written more confidently than the code earns. Code rulings survive review because a test can break them; prose rulings survive because nothing tries.
 
 For behavioral interfaces/classes:
@@ -65,5 +65,8 @@ Never use in-repository `@src/*` aliases in public guide examples; reserve them
 - Keep `SKILL.md` concise and route conditional detail to one-level `references/`.
 - Frontmatter contains only `name` and a trigger-focused `description`.
 - Do not put model routing or package version catalogs in a skill.
-- Validate every referenced resource and `agents/openai.yaml`; do not leave template TODOs or auxiliary README/changelog files.
+- Validate every referenced resource; do not leave template TODOs or auxiliary README/changelog files.
+- Write `agents/openai.yaml` as one root `interface:` mapping over exactly `display_name`, `short_description`, and `default_prompt`, in that order, each on its own two-space-indented line.
+- Give every one of those keys a non-empty single-quoted scalar, and write an apostrophe inside it as `''`.
+- Name the skill's own `$<directory>` token in `default_prompt`.
 - Keep provider bridges minimal: they load one canonical workflow and add no competing instructions.

package/dist/host/claude/rules/patterns.md

@@ -128,3 +128,13 @@ Use four orthogonal contract mechanisms:
   - guard-valid input is never rejected by its parser;
   - every parsed result satisfies its guard.
 - Derive parser and guard from one source or test the round trip.
+
+### Foreign contracts
+
+A value returned by an interface another package publishes is FOREIGN data. Own it, validate what you dereference, and narrow nothing.
+
+- Enforce the published contract and no more: accept unknown members, accept any implementation the interface admits including a class instance, and check each member as its published type declares it. A member typed `number` is not checked as an integer.
+- Reserve the exact-record guard for a record this package owns. Over a foreign interface it refuses values the interface permits and fails closed on a valid implementation.
+- Narrow nothing in an ownership transform. Where the published contract is wider than the copy mechanism, seal the value in place rather than refusing it.
+- Own a foreign value at arrival, validate the owned copy, and read the foreign object exactly once. Read count is this package's decision, so no result may depend on it.
+- Validate only what the package dereferences from a union it must narrow. Own a wide foreign record it merely carries and leave it unvalidated. State that asymmetry on the option that admits the implementation.

package/dist/host/claude/rules/quality.md

@@ -24,12 +24,10 @@ paths:
 - Never end a row as "hardened further." Replace any evaluative phrase with the concrete condition that closes the row.
 - Record a finding outside the matrix against the row that owns it, for the next matrix. Do not reopen this one.
 
-## Run it, don't argue it
+## Probes before arguments
 
 A question a probe can settle is settled by the probe, whether or not anyone has disputed it. Reasoning decides what to run and what the result means. It does not replace the run.
 
-This is a habit for your own work first, and a rule about disagreements second. Most unverified beliefs are never challenged by anyone — they are simply built on.
-
 - Test your own assumptions before you rely on them. You do not need a disagreement to justify a probe. If you are about to depend on what a function returns, what a config resolves to, what a flag does, or whether a path is even reached, run it and find out.
 - Treat a long deliberation about behaviour as the signal to stop and run something. Deliberation that a ten-line probe would have ended is the most expensive habit in this process, and it is invisible because it feels like rigour.
 - Verify a belief before stating it, or label it as unverified. An unverified assertion put into context becomes a fact for everything downstream, including other agents, and correcting it later costs more than the check would have.
@@ -39,6 +37,7 @@ This is a habit for your own work first, and a rule about disagreements second.
 - Bound the search before starting it, and put the bound in the brief. Name the benchmark, the population, or the row that ends it. An investigation with no stated stopping condition runs until attention runs out. This includes the case where the honest answer is that the limit is inherent and belongs in documentation rather than in code.
 - Treat a negative probe as evidence about the probe until its input is shown to reach the code under test. A pass proves nothing if the vector never arrived. Instrument the path, assert an observable side effect, or drive it through a door you can see.
 - When a report names a defect and your reproduction comes back clean, assume first that your vector was weaker than theirs, and go get their exact vector. Treating a failed reproduction as a disproof is the most common way a true finding is lost.
+- A reported vector the compiler rejects refutes the VECTOR, never the finding. Where a claim asserts reachability through a typed API, compile the exact vector under the project's own settings; re-derive one the types admit before dropping the finding, and record which vector was actually tested.
 - Reproduce a reported defect's cause before instructing a fix from it. A real symptom can carry a wrong diagnosis, and a fix aimed at the stated cause edits the wrong file while the defect survives.
 - Do not read a result into a tool's failure to find your probe. "No tests found", an empty match, a skipped file, a runner that resolved nothing — these report on the harness, not the subject. Confirm the probe was collected and executed first.
 - Prefer an observation over a derivation, including your own. When a measurement and an argument disagree, the argument is wrong until the measurement is shown to be broken.
@@ -63,6 +62,7 @@ A review that reads a diff finds what the diff shows. A review that tries to bre
 - Draw the negative control from outside the population the instrument covers. Name the instrument's membership rule first, then pick a control that rule excludes. A control sampled from constructs the instrument already handles proves only that it discriminates among those constructs, and says nothing about the class it silently cannot reach.
 - State an instrument's coverage beside its result. A conclusion inherits the instrument's scope, not the question's. An unstated coverage claim is read as complete, and it never is. A search proves something about the paths it walked, so name them.
 - Match the instrument to the question. A text search reports on text, so a claim about declarations, call sites, or structure needs the compiler or a parser instead. A pattern written for one spelling of a construct reports on that spelling alone. A path check answers relative to the directory it runs from, so resolve the inputs against their own base before reading a miss as a finding.
+- Name the rival reading the instrument must exclude, and show it reports differently under that reading. Give independent measurements independent state: one counter shared across members reports read order and per-member read count identically, so a result consistent with both measured neither.
 - Report a question unanswered rather than answering it with a weaker instrument. A fallback that measures something adjacent returns a confident wrong answer, and nothing downstream can tell that answer from the real one — searching commit messages for a release when the question is where a version changed will match some release, just not the one asked about. Name the substitute and what it actually measures, or say the question is open.
 - State what the controls established and what they did not. An instrument certified only from the inside is trusted exactly where it has never been tested.
 - Treat a gap between what an instrument says it checks and what it actually matches as a defect in the instrument, not as a documented limit. A recorded blind spot buys trust only when everything outside it is genuinely covered.
@@ -80,7 +80,8 @@ A review that reads a diff finds what the diff shows. A review that tries to bre
 - Let reachability bound the fix. A defect reachable through the package's own shipped code or a documented extension seam falsifies its claim and is repaired now.
 - Document the obligation instead when a defect is reachable only through a hypothetical foreign implementation of a contract this package publishes. State it on the interface that owns it and prove the documentation. Do not build coordination machinery against a requirement nobody wrote down. Attacks are unlimited; reachable ones are not, and only the reachable set is a work list.
 - **Three rounds at one seam is the budget.** Repeated rounds against one seam are evidence about the design, not evidence of diligence. At the third round the next unit is a ruling — on the threat model, the mechanism, or the boundary — taken with the same adversarial pass a design gets, not a fourth repair.
-- Write the round count down when the seam opens, so it is a fact rather than a feeling. A seam that has consumed more rounds than the rest of the matrix combined has already answered the question.
+- Write the round count down in the capability/defect matrix row that owns the seam, when the seam opens, so it is a fact rather than a feeling. A seam that has consumed more rounds than the rest of the matrix combined has already answered the question.
+- State the ruling that ends a seam as three things: the invariant the code will obey, the constraint bounding it against over-correction, and the interface where a consumer meets the obligation. A ruling that names only the defect it replaces produces the opposite defect next round.
 - Give every behavioural audit the means to run its attacks. An auditor that cannot execute cannot falsify a behavioural claim: it returns derivations, and a derivation reads exactly like a verdict while being a different thing — it will confirm a claim one probe would break. Treat a report with no executed evidence as a review of the source, and label it as such.
 
 ## Ecosystem reuse

package/dist/host/claude/rules/tests.md

@@ -35,6 +35,7 @@ paths:
 - Measure an elapsed interval with `performance.now()`, never `Date.now()`. `Date.now()` returns whole milliseconds, so an interval built from two of its readings truncates at both ends and can under-report by a millisecond — enough to fail a boundary assertion against a timer that behaved correctly. `performance.now()` is monotonic and sub-millisecond, and it does not move when the wall clock does.
 - Give a conditional skip the mechanism that makes it inapplicable, cited, not the platform name alone. A test skipped on a platform is a test nobody re-examines; a test skipped because a named API rejects a named case is one anybody can re-check.
 - A regression test records the exact command and its failing count before the fix, and the same command's passing count after.
+- The revert that proves a repair reddens exactly the test that names the defect. Keep the import and collection graph valid while reverting, and confirm the named test was collected. A revert that reddens anything beyond that test broke the harness, and its count is not evidence.
 - Use `it.todo()` only for explicitly out-of-scope roadmap work, never to complete the current request. Every `.skip` or conditional skip has a narrow verifiable applicability reason.
 - Do not create test files solely for `constants.ts`, barrels, error definitions, or `types.ts`.
 - Run the narrowest relevant Vitest project during development; do not run the entire suite casually.
@@ -44,20 +45,24 @@ paths:
 A proof that covers the workspace instead of one module has a fixed location, so no package invents
 its own:
 
-| Path                         | Proves                                                                                                |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `tests/policy.test.ts`       | Every source file obeys the syntactic coding and placement law                                        |
-| `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs, and the `configs/` leaves behind them |
-| `tests/guides.test.ts`       | Every documented API exists and every public API is documented                                        |
-| `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks                                         |
-| `tests/distribution.test.ts` | The packed package installs and resolves through its public exports                                   |
-| `tests/integration.test.ts`  | The package's features work together end to end across environments                                   |
-| `tests/service/**/*.test.ts` | The live external services this package drives, driven for real                                       |
+| Path                         | Proves                                                                                                                         |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `tests/policy.test.ts`       | Every source file obeys the syntactic coding and placement law                                                                 |
+| `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs, and the `configs/` leaves behind them                          |
+| `tests/guides.test.ts`       | Every documented API exists, every public API is documented, and every executable fence returns what the guide says it returns |
+| `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks                                                                  |
+| `tests/distribution.test.ts` | The packed package installs and resolves through its public exports                                                            |
+| `tests/integration.test.ts`  | The package's features work together end to end across environments                                                            |
+| `tests/service/**/*.test.ts` | The live external services this package drives, driven for real                                                                |
 
 - `.claude/rules/workspace.md` names the Vitest project each location belongs to.
-- The `guides` project runs in Node with the browser disabled. Its subject is
-  documented-name-to-real-export. A proof that renders a component and compares it against a
-  definition is a composition and belongs in an `integration.test.ts` scoped to its directory.
+- The `guides` project runs in Node with the browser disabled. Its subject is what the guide
+  claims: that every documented name resolves, and that every fence asserting a value returns
+  that value. A proof that renders a component and compares it against a definition is a
+  composition and belongs in an `integration.test.ts` scoped to its directory.
+- Transcribe each flagship fence and assert the values its comments claim. Name resolution is
+  not a behavioural proof, so a fence documenting a value the code contradicts passes every
+  parity assertion. Change a fence, change the transcription beside it.
 - `integration.test.ts` is a reserved filename at any level. It names a scope rather than a module,
   so the mirror rule does not reach it; its scope is the directory it sits in.
 - An integration test is an end-to-end test: it composes the package's own features and drives them