@orkestrel/scaffold 0.0.18 → 0.0.20

package/dist/host/agents/skills/orkestrel-debrief/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: orkestrel-debrief
+description: Look back at a long campaign to learn from its mistakes and successes and improve the agents, rules, skills, and processes that ran it. Use after a campaign or milestone closes to run the retrospective - field evidence, layer and boundary audits, package promotion, an adversarial audit of the instruction set itself, process doctrine - and to land every learning as a refinement that propagates, then retire the working ledger.
+---
+
+# Debrief a closed campaign
+
+## Load authority
+
+Read the current files in this order:
+
+1. `AGENTS.md`.
+2. Every applicable `.claude/rules/*.md`; the documentation and quality laws bind every
+   ledger entry and every refinement this skill produces.
+3. The references this round needs: [instruction-audit.md](references/instruction-audit.md)
+   before auditing the agent/rule/skill/process layer;
+   [field-testing.md](references/field-testing.md) before running or judging a live field
+   pass of an agent-facing surface.
+4. `guides/README.md`, the governing guides for what the campaign built, and `ROADMAP.md`.
+
+The user's current instruction wins. The debrief judges the artifact AND the process that
+produced it; neither is exempt, and successes are captured as deliberately as mistakes —
+a practice that worked is codified so it repeats, not merely survived.
+
+## The debrief laws
+
+- **The campaign record is the primary source.** Dispatches, deviation reports, audit
+  verdicts, gate outputs, commit messages, and live transcripts are evidence; recollection
+  is not. Quote verbatim — a paraphrase cannot be re-verified later.
+- **Use it before you judge it.** Where the campaign built something consumable — a
+  package, an app, an agent-facing surface — drive it with representative real consumers
+  before writing findings about it. For agent-facing surfaces, follow
+  [field-testing.md](references/field-testing.md).
+- **Every finding ends in exactly one bucket**: fix now; agent refinement; rule
+  refinement; skill refinement or creation; process refinement (orchestration contract);
+  package promotion; guide truth; roadmap; stays as-is with the reason; or dropped on the
+  record with the refuting evidence. A finding with no bucket is an unfinished debrief.
+- **Fixes are re-proven by the evidence class that found them.** A defect found in live
+  use closes with live use; a process failure closes when the next campaign round runs
+  the corrected process.
+- **Portable versus resident.** Learnings reusable beyond the repository — process
+  doctrine, role charters, rules, skills — land in the portable canon and propagate
+  through the scaffold host inventory. Repository truth lands in the guide; forward work
+  in `ROADMAP.md`. Nothing load-bearing stays only in the ledger.
+- **The ledger is ephemeral.** Fold every surviving truth into its destination, then
+  delete the folder on the owner's explicit go-ahead — never silently, never as residue.
+
+## Run the round
+
+1. **Scope and gather.** Name the campaign(s) under debrief. Assemble the record: unit
+   ledger, deviations and recoveries, audit verdicts and their reconciliations, gate
+   history, and any live transcripts. State what evidence exists and what must be
+   produced fresh.
+2. **Field evidence.** Drive what was built with real consumers where a consumable
+   surface exists. Record every pass verbatim.
+3. **Artifact audits.** Layer and boundary truth: does app code belong a layer down in
+   src, does src carry application policy, does either duplicate a declared ecosystem
+   primitive? Package promotion: what grew into a reusable mechanism that belongs in an
+   existing package or justifies a new one — mapped dependency-first so promotion order
+   is executable. Every row ends implement, repair, retain, or intentionally exclude,
+   with evidence.
+4. **Process retrospective.** Walk the campaign record for both failure and success:
+   dispatches that deviated and why; recoveries that worked (codify the mechanism that
+   saved them); estimates versus observed durations; audit rounds that caught real
+   defects versus rounds that churned; anything the orchestrator absorbed that should
+   have been dispatched or dispatched that it should have owned.
+5. **Instruction-set audit.** Audit the agents, rules, skills, and orchestration
+   contract themselves against the campaign record, using the adversarial method in
+   [instruction-audit.md](references/instruction-audit.md). What confused an executor is
+   a defect in the instruction, not the executor.
+6. **Reconcile into the ledger.** Number the findings, attach verbatim evidence, bucket
+   every one. Where two audit lanes disagree, rule each divergence on the record with
+   the reason.
+7. **Land the refinements.** Dispatch fix-now findings as bounded units under the
+   repository's engine contract; make the canon edits (charters, rules, skills,
+   orchestration contract) with the owner's direction where the root contract is
+   touched; re-prove per the law above.
+8. **Propagate.** Portable changes are made in the scaffold repository's host inventory,
+   staged, gated, and pushed — editing one project's checkout propagates nothing. Verify
+   the generated-workspace proofs stay green so new projects inherit the refined canon.
+9. **Dispose.** Present the disposition map — finding table with carriers, the canon
+   delta, what remains open — and delete the ledger only on the owner's explicit
+   go-ahead.
+
+## Verdict shape
+
+Each round ends with one fixed report: the finding table (id, evidence pointer, bucket,
+carrier), the canon delta (files created or changed, per layer: agents, rules, skills,
+process, guide, roadmap), the re-proof evidence, and exactly one terminal line —
+`DEBRIEF: FOLDED` when every finding has a carrier and the propagation is pushed, or
+`DEBRIEF: OPEN` with the blocking items.

package/dist/host/agents/skills/orkestrel-debrief/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Debrief Closed Campaign'
+  short_description: 'Fold a closed campaign into portable truth on field evidence'
+  default_prompt: 'Use $orkestrel-debrief to debrief the closed campaign: field passes, findings ledger, fix loops, canon refinement, propagation, disposal.'

package/dist/host/agents/skills/orkestrel-debrief/references/field-testing.md

@@ -0,0 +1,75 @@
+# Field testing an agent-facing surface
+
+The method for producing the live evidence a debrief judges by. Proven across the
+supervisor MCP campaign's five-model roster; portable to any surface a model consumes.
+
+## The tier ladder
+
+Test from the top down, and do not stop at the tier that passes:
+
+1. **Frontier** (the harness's default model) — proves the surface works at all.
+2. **Mid tier** (e.g. a codex mechanical model) — proves the surface survives a harness's
+   schema abbreviation and a model that reads less carefully.
+3. **Small harness-native** (e.g. Haiku, a codex high-volume model, a cursor composer) —
+   the acceptance tier: these must walk the surface unaided, or the surface is not done.
+4. **Local floor** (a quantized 2B-class model through a real tool-calling client) — not
+   an acceptance gate; a stochastic probe that exposes teaching gaps nothing else hits.
+   Its residual failures must be provably consumer-floor (malformed emission, attention
+   loss), never surface darkness — every refusal it received must have named the fix.
+
+## The pass discipline
+
+- **Goal-only prompts.** State the outcome, never the shape: no field names, no schema
+  hints, no tool names beyond the surface's own. The teaching surface must carry
+  everything else. Identical wording across models; only identifiers vary.
+- **Fresh state per round.** New workflow/resource ids each round; a fresh server on the
+  exact build under test. Never let a model inherit a sibling's residue.
+- **No coaching, no retries by hand.** The transcript ends when the model finishes or its
+  cap fires. A human nudge invalidates the pass.
+- **Caps and journals.** Every pass runs as a tracked background command under a hard
+  time cap with its transcript journaled; the journal is the evidence of record.
+
+## Capture the reasoning, not just the calls
+
+Where the runtime exposes thinking (local runtimes expose it directly; harness stream
+formats carry interstitial text), record it. The call log shows WHAT failed; the trace
+shows WHY — and the why is what the fix targets.
+
+## The confusion-signature catalog
+
+Read every trace against these; each maps to a class of surface fix:
+
+| Signature               | What it looks like                                                     | The fix class                                                                                              |
+| ----------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Rationalized silence    | The model meets an anomaly, invents a plausible cause, reports success | A silent path must refuse loudly; false affordances removed                                                |
+| Guess loop              | Repeated invented shapes with no reading between attempts              | The critical shape belongs in the description text, stated early                                           |
+| Abbreviation blindness  | The model names what it cannot see ("the abbreviated schema")          | Teaching moved to the surface every harness shows intact                                                   |
+| One-correction-per-step | A refusal names two defects; the model fixes one and keeps the other   | Refusals name ALL missing and unexpected items every time                                                  |
+| Opaque-wall regression  | A correct structure abandoned after an unnamed refusal                 | Every refusal names the subject, path, expectation, and candidates                                         |
+| Repetition fixpoint     | The identical failing call repeated verbatim                           | The refusal must change the caller's information state; if it already does, the residual is consumer-floor |
+
+## The teaching-surface doctrine
+
+What the field passes repeatedly prove:
+
+- **Descriptions are the surviving surface.** Harnesses abbreviate nested schemas;
+  the tool description reaches every model intact. The critical path — a worked example,
+  the key nesting, the reply shape — lives there, importance-first, so a model that
+  stops reading early still gets it.
+- **Every refusal orients, names, or corrects.** Subject, exact key path, expected
+  shape, valid candidates, missing versus unexpected — a refusal that names nothing ends
+  runs; a refusal that names everything converges even a 2B model.
+- **Strictness with teaching beats tolerance.** Never coerce, never silently drop;
+  refuse with the correction in the message. Encode untrusted identifiers (JSON-encoded,
+  length-capped) so hostile input cannot forge or balloon a diagnostic.
+- **Acknowledge or state, never both.** Mutations return acknowledgements; reads return
+  state; the split is stated in both tools' descriptions so neither is polled for the
+  other's job.
+
+## The scoreboard
+
+Report each round as a table: model, harness, calls, failed calls, outcome, and the
+delta from the prior round. A tier passes when its models complete the goal with zero
+failed calls and no out-of-band reading (no source excavation, no filesystem search —
+watch for it in the transcript; it means the surface leaked its teaching job to the
+repository).

package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md

@@ -0,0 +1,70 @@
+# Auditing the instruction set
+
+The method for judging the agents, rules, skills, and orchestration contract against a
+campaign's record. Proven across two debrief rounds; the instruction layer is code — it
+gets the same adversarial, evidence-first treatment as any surface.
+
+## Two blind passes, one brief
+
+Run a subjective lane and an objective lane on the SAME brief, in parallel, neither
+seeing the other's answer before both return:
+
+- **Subjective** (design-fit engine): coherence of the role model, charter voice, whether
+  each role's job is one job, whether the skill family reads as one system.
+- **Objective** (correctness engine): evidence-only sweeps of the actual files and the
+  campaign record — the lanes below.
+
+Reconcile into rulings; every divergence gets a ruled row with the reason. Convergent
+findings adopt without contest; a finding neither lane can substantiate dies on the
+record.
+
+## The objective lanes
+
+- **Duplication diff.** Whole-line and obligation-level comparison across charters, rules,
+  and skills. A charter that restates a rule drifts from it; a rule stated twice has two
+  owners.
+- **Mechanical-equivalence groups.** Cluster roles by frontmatter (tools, model, effort,
+  mode). Two roles in one group are either genuinely distinct by context binding — or a
+  duplicate.
+- **Charter-versus-usage drift.** For each role, compare the charter's promises against
+  how the campaign actually dispatched it: unused powers, exercised powers the charter
+  never granted, deviation reports the charter's wording caused.
+- **Promise-versus-tooling gaps.** A charter that promises verification it has no tool to
+  perform (a registry check with no network, a capture claim with no browser) either
+  gains the bounded tool or states plainly that the evidence comes supplied.
+- **Roster completeness on both axes.** The role set spans model agents (engine bridges
+  and pins) and task agents (job-pinned lanes with their context preset). Check each axis
+  for holes against the campaign's actual work classes: implementation (mechanical,
+  app-layer, judgment-bearing per engine), evidence (research, reconnaissance,
+  conformance, gates, ecosystem), design, review, distillation. A work class the
+  campaign routed awkwardly — absorbed by the orchestrator, forced onto the wrong tier,
+  or dead when a bench was dark — names a missing or mischartered role.
+
+## Refinement classes
+
+Findings land as one of:
+
+- **Role create / restore / retire.** Retirement requires more than duplication evidence:
+  when a charter merely restates rules, the first remedy is a thin reference-BINDING
+  charter (the role keeps its context preset and its dispatch ergonomics); retire only
+  when the job itself is not distinct. Record the lesson of the reversed retirement: a
+  role that was "mechanically identical" by frontmatter still carried a distinct context
+  bundle worth keeping.
+- **Rule additions, one law each.** A campaign lesson that generalizes becomes one law in
+  the owning rule file — never a new file per lesson, never a paragraph where a sentence
+  binds.
+- **Root-reference trims.** Restatement of root laws in leaf files shrinks to a
+  reference; the root stays the single owner.
+- **Charter refinements.** Wording that caused a deviation is a defect; fix the charter,
+  not the executor.
+- **Skill refinements / creation.** A workflow the campaign repeated twice is a skill; a
+  skill step the campaign always skipped or always overrode is wrong.
+- **Orchestration-contract refinements.** Laws the orchestrator learned (cap sizing,
+  probe-first, journal-first, verdict shapes, launch ownership) land in the operating
+  contract, mirrored across providers.
+
+## Mirror discipline
+
+Every roster or contract change lands on all provider surfaces in the same round: the
+Claude charters, the Codex mirrors, and both operating-contract role tables. An
+unmirrored refinement is a new drift seeded on purpose.

package/dist/host/agents/skills/orkestrel-harden-package/SKILL.md

@@ -42,21 +42,23 @@ Load [hardening.md](references/hardening.md) for the hardening lane and for any
 1. **Bound the campaign.** Record requested outcomes, in-scope environments/domains, explicit exclusions, supported hosts, dirty files, and evidence needed for acceptance.
 2. **Map before editing.** Trace public types, implementations, callers, tests, guides, exports, runtime boundaries, installed Orkestrel dependencies, and applicable legacy/upstream references.
 3. **Establish the intended contract.** Build a capability/defect matrix. Separate verified fact from inference. Mark each row implement, repair, retain, or exclude with a reason.
-4. **Design types first.** Update guide/spec intent and `*/types.ts` before implementation. Preserve dependency direction, single-word entity APIs, and mechanism-over-policy boundaries. Do not retain compatibility shims.
-5. **Implement completely.** Finish every in-scope branch. Reuse exact installed Orkestrel primitives when their semantics match. Never hide incomplete behavior behind a TODO, skip, empty branch, or success-shaped placeholder.
-6. **Consolidate.** Run the complete centralization and wrapper sweep. Update all call sites to the real symbol rather than leaving aliases or 1:1 delegates.
-7. **Challenge seams.** Add deterministic tests for invariants, boundaries, failures, lifecycle, cleanup, cancellation, concurrency, hostile input, and resource pressure as applicable. Use real implementations and protocol-faithful fixtures. Never use mocks or fakes.
-8. **Use live services deliberately.** Put real external services/models in their dedicated project, require readiness, and make each request minimally sufficient, robust, and behaviorally meaningful.
-9. **Document the final behavior.** Update the governing guide, examples, method tables, limitations, and parity coverage. Document architectural limits honestly.
-10. **Audit completion.** Inspect test discovery, `.todo`/`.skip`/conditional skip use, source/test helper duplication, exports, environment isolation, unexpected text corruption, and the entire diff.
-11. **Verify.** Run the repository-prescribed gates in order and inspect the generated outputs relevant to the request.
-12. **Review independently.** When orchestration is available, require a design-fit reviewer, an objective correctness/constraints analyst, and a mechanical checker; add an adversarial pass for security, concurrency, destructive paths, or external input. Resolve every required finding, then rerun affected verification.
+4. **Design types first.** Update guide/spec intent and `*/types.ts` before implementation, under the root design laws. A contract that needs a compatibility shim is the wrong contract.
+5. **Implement completely.** Finish every in-scope branch and reuse the exact installed Orkestrel primitives whose semantics match. The root completion law decides what may not be left behind.
+6. **Prove each defect before repairing it.** A repair begins with a test that fails for that defect: record the exact command and its failing count before the fix and the same command's passing count after. A repair with no red-then-green record is unproven.
+7. **Consolidate.** Run the complete centralization and wrapper sweep. Update all call sites to the real symbol rather than leaving aliases or 1:1 delegates.
+8. **Challenge seams.** Add deterministic tests for invariants, boundaries, failures, lifecycle, cleanup, cancellation, concurrency, hostile input, and resource pressure as applicable, under the test rules' real-implementation law.
+9. **Use live services deliberately.** Put real external services/models in their dedicated project, require readiness, and make each request minimally sufficient, robust, and behaviorally meaningful. When the claim is that a foreign client can use this package, drive one representative real client end to end.
+10. **Document the final behavior.** Update the governing guide, examples, method tables, limitations, and parity coverage. Document architectural limits honestly.
+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.
+12. **Verify.** Run the repository-prescribed gates in order and inspect the generated outputs relevant to the request.
+13. **Review independently, and never by the author.** When orchestration is available, require a design-fit reviewer, an objective correctness/constraints analyst, and a mechanical checker; add an adversarial pass for security, concurrency, destructive paths, or external input. A unit's auditor is the 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.
 
 ## Accept the result
 
 Do not accept “mostly complete,” “tests pass” without adequacy review, or a builder's self-report. Completion requires:
 
 - all requested capabilities implemented or explicitly proven out of scope;
+- red-then-green evidence for every repaired defect;
 - public contract, implementation, tests, guides, and generated outputs aligned;
 - no unresolved centralization, wrapper, dependency-reuse, test-discovery, lifecycle, security, or text-integrity finding;
 - exact command evidence for every final gate.

package/dist/host/agents/skills/orkestrel-harden-package/references/centralization.md

@@ -1,85 +1,70 @@
 # Centralization and simplification
 
-## Inventory declarations
+Placement, kind purity, the wrapper test, the no-nested-function law, and barrel law live
+in `.claude/rules/architecture.md`; shared test infrastructure and helper placement live in
+`.claude/rules/tests.md`. This reference adds only the sweep those laws assume: what to
+inventory, how to classify, and what must be proven before acceptance.
 
-Inspect every touched implementation and centralized file, then sweep the full affected environments.
+## Inventory what you touched
 
-For implementation files, inventory:
+Inspect every touched implementation and centralized file, then sweep the full affected
+environments.
 
-- interfaces and type aliases;
-- module constants and data;
-- free functions, guards, parsers, factories, and schemas;
-- function declarations or assignments inside functions/methods;
-- multiple classes;
-- imports or exports left behind after moves.
+| Where               | Inventory                                                                                                                                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Implementation file | Interfaces and type aliases, module constants and data, free functions/guards/parsers/factories/schemas, function declarations or assignments inside bodies, extra classes, imports and exports stranded by a move |
+| Centralized file    | Every module declaration: does it match that file's kind, is it exported, is it reachable from the sole public barrel when public, does it carry direct behavioral coverage when it carries logic                  |
+| Environment root    | Every declaration promoted there: at least two consuming modules, or it belongs to the owning module's centralized file                                                                                            |
 
-Implementation files contain imports and one class. The rare runtime-self-contained entrypoint exception must be literally required for execution and must explain why sibling imports cannot work.
+The rare runtime-self-contained entrypoint exception must be literally required for
+execution and must explain why sibling imports cannot work.
 
-For centralized files, inventory every module declaration. Each declaration must:
+## Classify every function
 
-- match that file's kind;
-- be exported;
-- be reachable from the sole public barrel when public by repository law;
-- have direct behavioral coverage when it contains logic.
+| Signal                                     | Home                                                 |
+| ------------------------------------------ | ---------------------------------------------------- |
+| Reaches instance state or a sibling method | Class method                                         |
+| Pure self-contained computation            | Exported centralized helper, parser, compiler, guard |
+| Defining recursive or compositional spine  | Class method, after extracting its pure leaves       |
+| Trivial and genuinely one-use              | Inline it into the caller                            |
 
-Promote a declaration to an environment root only when multiple modules consume it. Otherwise keep it in the owning module's centralized file.
+Never move logic into a nested function to evade centralization. An anonymous callback
+passed directly to another operation stays a callback, not a hidden helper declaration.
 
-## Apply the leaf test
+## Hunt the wrapper
 
-Classify each function:
+Search callers and callees for one-line delegates, pass-through factories, getters that
+rename another public getter, duplicate guards or parsers a declared dependency already
+supplies, compatibility aliases and re-exports, and functions whose only purpose is
+avoiding a downstream rename. The architecture rules' wrapper test decides each one; a
+survivor owns a real boundary, invariant, composition, translation, lifecycle, or
+materially narrower contract. Otherwise use or rename the real symbol and update every
+consumer.
 
-1. Instance state or sibling-method access: class method.
-2. Pure, self-contained computation: exported centralized helper/parser/compiler/etc.
-3. Defining recursive/compositional engine spine: class method after extracting its pure leaves.
-4. Trivial, genuinely one-use expression: inline it.
-
-Never move logic into a nested function to evade centralization. Anonymous callbacks passed directly to another operation remain callbacks, not hidden helper declarations.
-
-## Remove superfluous wrappers
-
-Search callers and callees for:
-
-- one-line helper delegates;
-- pass-through factories;
-- getters that merely rename another public getter;
-- duplicate guards/parsers already supplied by a declared dependency;
-- compatibility aliases and re-exports;
-- functions whose only purpose is avoiding a downstream rename.
-
-A wrapper survives only if it owns a boundary, invariant, composition, translation, lifecycle, or materially narrower contract. Otherwise use or rename the real symbol and update every consumer.
-
-Do not hollow a class into public methods that each forward to one helper. Keep meaningful orchestration on the entity and export only pure leaves.
+Do not hollow a class into public methods that each forward to one helper.
 
 ## Consolidate tests
 
-Sweep test files for repeated or reusable:
-
-- input and result records;
-- builders and factories;
-- recorders and event capture;
-- wait/readiness helpers;
-- temporary workspace or fixture-server setup;
-- browser/DOM builders and event factories;
-- service request builders and response assertions.
-
-Move host-independent helpers to `tests/setup.ts`; Node helpers to `tests/setupServer.ts`; browser helpers to `tests/setupBrowser.ts`; styles helpers to `tests/setupStyles.ts`; and live-service helpers to that project's dedicated setup.
-
-Use customizable factories and inert stubs for data shapes. A scripted boundary stub may implement the real interface/protocol minimally to drive the system under test, but must not reproduce project-owned behavior or replace the integration being claimed. Otherwise use the real implementation, a temporary resource, a protocol-faithful fixture server, or the real external service.
-
-Prefer recorders over spies. Do not use mocks or fakes.
+Sweep test files for repeated or reusable input and result records, builders and
+factories, recorders and event capture, wait and readiness helpers, temporary workspace or
+fixture-server setup, browser and DOM builders, event factories, and service request
+builders or response assertions. Move each into the setup file its environment owns.
 
-Add focused tests for every exported function extracted from production code. Do not create isolated tests for declaration-only types, constants, barrels, or error definitions.
+Add focused tests for every exported function extracted from production code. Do not create
+isolated tests for declaration-only types, constants, barrels, or error definitions.
 
-## Run the cleanup sweep
+## Prove the sweep
 
 Before acceptance, prove:
 
 - no stray declarations remain in implementation files;
 - no non-exported or wrong-kind declaration remains in centralized files;
-- no prohibited nested function declaration/assignment remains;
+- no prohibited nested function declaration or assignment remains;
 - no duplicate or rename-only wrapper remains;
 - every move updated imports, barrels, guides, and tests;
 - test helpers are consolidated without over-generalizing one-off setup;
-- files are valid UTF-8 and contain no replacement characters, mojibake, unintended control characters, or accidental trailing debris.
+- files are valid UTF-8 with no replacement characters, mojibake, unintended control
+  characters, or accidental trailing debris.
 
-Review the complete diff after formatting. Formatting cannot substitute for the structural sweep.
+Review the complete diff after formatting. Formatting cannot substitute for the structural
+sweep.

package/dist/host/agents/skills/orkestrel-harden-package/references/hardening.md

@@ -21,12 +21,20 @@ For each applicable seam, state the invariant, failure mode, observable result,
 
 Test through public behavior with:
 
-- real package classes and composed managers;
-- temporary directories/files;
-- actual local sockets and protocol-faithful fixture servers;
-- actual Chromium-family browsers where the browser is the system under test;
-- actual installed dependencies;
-- actual external service/model projects when their behavior is the subject.
+| Seam                                    | The real thing it must be driven with                                    |
+| --------------------------------------- | ------------------------------------------------------------------------ |
+| Package behavior                        | Real package classes and composed managers                               |
+| Filesystem                              | Temporary directories and files                                          |
+| Network protocol                        | Actual local sockets and protocol-faithful fixture servers               |
+| Browser                                 | An actual Chromium-family browser when the browser is the system         |
+| Declared dependency                     | The actual installed dependency                                          |
+| External service or model               | The real service in its dedicated project when its behavior is the claim |
+| Third-party client or protocol consumer | One representative real foreign client, driven end to end                |
+
+A third-party seam is the one case where the package's own tests cannot close the claim:
+protocol tests prove the protocol, and only a real client of that class proves the
+integration. Drive it end to end, record the exact commands, and record what that client
+could NOT reach as an honest limit rather than an untested assumption.
 
 Never use mocks, behavioral fakes, module replacement, or framework spies. Use recorders for callbacks and customizable data factories/stubs for inert shapes.
 

package/dist/host/agents/skills/orkestrel-polish-surface/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: orkestrel-polish-surface
+description: Drive a rendered or externally driven surface to shipped quality through capture-evidence verdict rounds. Use when asked to polish an interface, bring a rendered surface to enterprise grade, judge what actually renders rather than what the source claims, reconcile design, state-truth, and inventory findings into fix units, or converge repeated review rounds on captured proof. Run one round for a narrow request; run the full campaign for a polish or production-readiness request.
+---
+
+# Polish a rendered surface
+
+## Load authority
+
+Read the current files in this order:
+
+1. `AGENTS.md`.
+2. Every applicable `.claude/rules/*.md`. The style, browser, test, and documentation
+   laws bind every fix unit; this skill adds only the campaign.
+3. [capture-harness.md](references/capture-harness.md) before building, eyeballing, or
+   trusting a portfolio.
+4. `guides/README.md`, the governing guide for the surface, and `ROADMAP.md` when present.
+5. The authoritative `*/types.ts` for the surface, its components and partials, and the
+   shipped resolved cascade of every stylesheet the surface actually loads.
+
+Treat the current user instruction as authoritative. Treat repository rules as the coding
+contract and this skill as the workflow. Preserve dirty and user-owned work.
+
+## Judge the rendering, not the source
+
+A claim about a rendered surface is proven by capture, never by reading the code that was
+supposed to produce it. Source-reading review passes a component that renders nothing.
+
+- The portfolio IS the review input: captures at both viewports and both themes, an
+  accessibility snapshot, and an interaction log.
+- Source is corroboration for a mechanism, never the proof that the surface shows it.
+- A claim the portfolio cannot show is unproven, not passed. Say so.
+- The same law governs an externally driven surface: a compatibility claim is proven by
+  driving it with a representative real client, not by its own tests.
+
+## Select the scope
+
+Choose the smallest scope that satisfies the request:
+
+- **Verdict:** one portfolio, one lane, no fixes.
+- **Round:** portfolio → three independent verdicts → reconciliation → fix units →
+  recapture.
+- **Campaign:** rounds repeated until one terminal converged line, then independent gates.
+
+A narrow verdict request does not authorize fixes. A polish request authorizes fixing every
+confirmed finding in scope and rebuilding the harness gaps the verdicts expose.
+
+## Execute the campaign
+
+1. **Build the portfolio.** Produce the full evidence set with the harness reference, then
+   eyeball every artifact yourself before spending a verdict round on it. An unexamined
+   portfolio buys harness bugs at verdict prices.
+2. **Seed candidates.** Turn your own mid-integration observations into numbered
+   confirm-or-refute candidates inside the verdict brief. Observations that stay in your
+   head are neither evidence nor findings.
+3. **Take three independent verdicts** on the SAME portfolio, in the fixed shape below, no
+   lane seeing another's answer before all have returned. The three work classes are
+   subjective design fit; objective state truth; and mechanical inventory of copy, classes,
+   icons, and accessibility attributes.
+4. **Reconcile.** Confirmed findings get carriers; refuted findings die on the record with
+   the evidence that killed them; conflicts get a dated ruling. Then walk the reconciled
+   list once and name the fix-brief item carrying each finding — a finding with no carrier
+   is a dropped finding, and it will cost the next round.
+5. **Dispatch serialized fix units,** objective lane first because it changes the ground
+   truth the subjective lane reads. Each unit records the failing proof before the
+   repair — the exact command and its red count — and the same command's green count
+   after. Commit each accepted unit before dispatching the next.
+6. **Cross-audit.** A fix unit's auditor is the engine that did not write it. Same-engine
+   re-review returns the author's own blind spot.
+7. **Recapture,** repairing every harness gap the verdicts exposed, and re-verdict against
+   the new portfolio, not the old one.
+8. **Iterate to the terminal line.** Repeat rounds until every lane returns converged.
+9. **Verify independently.** An independent runner executes the repository-prescribed
+   gates; a fixer's own report never establishes green.
+
+## Fix the treatment, not the symptom
+
+- Resolve every visual treatment in the shipped cascade before writing it; a dependency's
+  own default rules decide what a bare element renders as.
+- Prove a defect with a test that fails for that defect before the repair exists.
+- Do not narrow a selector, add a local exception, or restyle one instance to make a
+  capture pass while the underlying rule stays wrong.
+- When a law of the repository genuinely conflicts with the surface's required anatomy,
+  stop and report both horns with evidence. An improvised local exception poisons an
+  enforced invariant.
+
+## Return the fixed verdict shape
+
+Free-form verdicts cost one reconciliation pass each. Every verdict returns:
+
+- one line per item, in the brief's numbering:
+  - `RENDERED-PROVEN(<capture>)` — the artifact shows it;
+  - `REGRESSED(<capture>, <what regressed>)` — the artifact shows it is now worse;
+  - `NOT-EVIDENCED(<what the portfolio lacks>)` — the portfolio cannot decide it;
+- referrals to another lane, each with the specific evidence and no verdict attached;
+- exactly one final line: `CONVERGED` or `ANOTHER ROUND(<item list>)`.
+
+Treat every `NOT-EVIDENCED` line as a harness question first and a product defect second.
+Triage it against the capture reference before it becomes a finding.
+
+## Accept the result
+
+Do not accept a source-only verdict, a self-audited fix unit, a round without a terminal
+line, or a green claim from the engine that wrote the code. Completion requires:
+
+- every confirmed finding fixed or explicitly ruled out of scope on the record;
+- a final portfolio whose captures show the accepted state;
+- red-then-green evidence for every defect unit;
+- every lane converged in one round against that final portfolio;
+- independent gate evidence.
+
+Report what changed, which capture proves each change, the exact test and gate results, and
+any residual risk the portfolio genuinely cannot settle.

package/dist/host/agents/skills/orkestrel-polish-surface/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Polish Rendered Surface'
+  short_description: 'Drive a rendered surface to shipped quality on captured evidence'
+  default_prompt: 'Use $orkestrel-polish-surface to bring this rendered surface to shipped quality on captured evidence.'