@orkestrel/scaffold 0.0.122 → 0.0.124

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +539 -0
  2. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1163 -0
  3. package/dist/bin/main.js +21 -19
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/agents/orchestration.md +13 -7
  6. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -3
  7. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -2
  9. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -2
  10. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +16 -3
  11. package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +18 -12
  12. package/dist/host/agents/skills/orkestrel-harden/references/document.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +2 -1
  14. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
  15. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +642 -0
  16. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +665 -0
  17. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +14 -13
  18. package/dist/host/agents/skills/orkestrel-parallel/references/claude-code.md +13 -13
  19. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
  20. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1433 -0
  21. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +2 -1
  22. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +18 -1
  23. package/dist/host/claude/AGENTS.md +1 -1
  24. package/dist/host/claude/agents/analyst.md +1 -1
  25. package/dist/host/claude/agents/builder.md +1 -1
  26. package/dist/host/claude/agents/distiller.md +2 -1
  27. package/dist/host/claude/agents/grok.md +2 -2
  28. package/dist/host/claude/agents/opus.md +2 -2
  29. package/dist/host/claude/agents/orkestrel.md +30 -30
  30. package/dist/host/claude/agents/reviewer.md +2 -2
  31. package/dist/host/claude/agents/scout.md +2 -1
  32. package/dist/host/claude/agents/verifier.md +1 -1
  33. package/dist/host/claude/rules/campaign.md +12 -11
  34. package/dist/host/claude/rules/documentation.md +1 -0
  35. package/dist/host/claude/rules/patterns.md +14 -0
  36. package/dist/host/claude/rules/quality.md +4 -1
  37. package/dist/host/claude/rules/tests.md +4 -0
  38. package/dist/host/claude/rules/writing.md +1 -1
  39. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  40. package/dist/host/codex/agents/analyst.toml +4 -1
  41. package/dist/host/codex/agents/astra.toml +1 -1
  42. package/dist/host/codex/agents/builder.toml +1 -1
  43. package/dist/host/codex/agents/distiller.toml +4 -2
  44. package/dist/host/codex/agents/grok.toml +5 -2
  45. package/dist/host/codex/agents/opus.toml +3 -3
  46. package/dist/host/codex/agents/reviewer.toml +6 -2
  47. package/dist/host/codex/agents/scout.toml +5 -1
  48. package/dist/host/codex/agents/verifier.toml +6 -1
  49. package/dist/host/guides/agent.md +1119 -457
  50. package/dist/host/guides/contract.md +226 -104
  51. package/dist/host/guides/database.md +12 -12
  52. package/dist/host/guides/ndjson.md +94 -21
  53. package/dist/host/guides/ollama.md +22 -18
  54. package/dist/host/guides/probe.md +29 -27
  55. package/dist/host/guides/reason.md +377 -114
  56. package/dist/host/guides/scaffold.md +43 -21
  57. package/dist/host/guides/study.md +538 -450
  58. package/dist/host/guides/tool.md +163 -58
  59. package/dist/host/manifest.json +70 -52
  60. package/dist/src/core/index.cjs +21 -20
  61. package/dist/src/core/index.cjs.map +1 -1
  62. package/dist/src/core/index.d.cts +1 -4
  63. package/dist/src/core/index.d.ts +1 -4
  64. package/dist/src/core/index.js +21 -20
  65. package/dist/src/core/index.js.map +1 -1
  66. package/dist/src/server/index.cjs +87 -8
  67. package/dist/src/server/index.cjs.map +1 -1
  68. package/dist/src/server/index.d.cts +50 -6
  69. package/dist/src/server/index.d.ts +50 -6
  70. package/dist/src/server/index.js +87 -10
  71. package/dist/src/server/index.js.map +1 -1
  72. package/package.json +15 -15
@@ -0,0 +1,642 @@
1
+ # Methods by package kind and scenario
2
+
3
+ Select the method for the package kind and scenario before choosing an instrument or a repair. Hold each reading to its run and each bar to its package, and carry neither to another package. A method's **Law** line names the rule that owns it, and "the law" in that block means that rule.
4
+
5
+ ## Select the method
6
+
7
+ | Package kind and situation | Deciding question | Method by branch |
8
+ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | Validation library or consumer: hot path versus entity admission | Does validation run per element or frame, or one time when an entity enters? | Repeated path: use a measured hand guard with a directional parity proof. Entity door: derive the guard from its shape where parity earns the cost, and compute diagnostics after refusal. § Choose validation by frequency and representation. A limit read after the cost is spent: § Enforce a bound before paying the refused work. A union parse that tries each arm: § Dispatch a union through its declared discriminant. |
10
+ | Interface, snapshot, or wire contract: open versus closed set | Who owns the representation? | Foreign interface: admit extra members and valid implementations, own the value one time, and validate dereferenced members. Owned persisted record: validate exactly before projection. Runtime result: project to wire before testing the wire contract. § State the representation before choosing exactness. |
11
+ | Parser receiving untrusted text | Is the admitted language declared, or is the parser accumulating bad examples? | Declare whole numeric forms and admitted neighbors, and refuse an undeclared whole token. Leave word-meaning tuning on the executable known-limits list unless a whole-model wrong decision meets the reopening condition. § Admit a declared numeric language instead of listing bad spellings; § Separate shape parsing, semantic admission, and authoring validation; § Distinguish syntax, terminal settlement, and intentional client cuts. The text of a refusal: § Make refusal text corrective without pretending to know intent. |
12
+ | Compiler with several walkers of one language | Are values stable between reads? | Stable: run generated algebraic laws across guard, parse, audit, and explain. Changing accessors or reentrancy: state separate temporal claims about one captured result, because a stable-value corpus does not close those claims. § Prove an instrument's domain and its actual sensitivity. |
13
+ | Collection, queue, graph, or renderer | Is the measured cost repeated traversal, construction, or unavoidable selected work? | Repeated construction: § Reuse work at its valid lifetime. Repeated copies or traversals: § Replace copy-on-append with an appropriate queue structure; § Search a cut instead of rendering every candidate; § Remove exponential work before adding a bound around it; § Own and freeze once, and price restoration separately; § Index against realistic text and retain small-registry costs. Work already within the consumer budget: § Close a cost question without building an optimization; § Derive the performance stop from the consumer; leave that work alone until its trigger fires. |
14
+ | Persistence and memoization | Must identity survive a sorting JSON store? | Yes: compare the declared JSON value and pin tie order separately. Positional prompt semantics: retain their explicit limits and claim no arbitrary JavaScript equality. § Make persisted identity match the declared value semantics. |
15
+ | Interactive scheduler | Is the aim throughput or a real host turn before a deadline? | Throughput: measure no-scheduler wall time. Responsiveness: measure heartbeat gaps, use a microtask control, and test cancellation and interleavings. Price the actual yield latency. § Yield real host turns and prove the interleavings they add. |
16
+ | Worker or learned router | Is there a crossover after transfer, validation, and decision overhead? | None: retain the fixed route. Present: compare against that route and a threshold, charge predictor cost, and test fresh and out-of-range populations. § Price the complete route before optimizing its kernel; § Charge a learned decision for the decision itself. A fit claimed portable across hosts: § Separate numeric bytes, predictions, and decisions. |
17
+ | Benchmark on a loaded host | Can the treatment be distinguished from host and process noise? | Interleave builds in one controlled slot, calibrate identical-side (A/A) runs and delivered sensitivity, and report uncertainty and host load. When the comparison is unreadable, report no result and do not gate on an old absolute baseline. § Calibrate the comparison, not merely the timer. A faster cell beside slower consumers: § Revert a speed-only change that misses its own acceptance. A duration or a ceiling cited as a gain: § Keep operational evidence in its own category. |
18
+ | Model experiment | Does the perturbation change persisted identity or the instrument? | Identity change: account for re-asks before interpreting noise. Instrument change: open another lineage. Unreached stratum: record it as unreached, not failed, and add no substitute arm without a rewritten question. § Separate model perturbation from cache-identity changes; § Size runs from observed work and preserve failed-run accounting. A claim that carries an outside source: § Preserve research provenance, qualifications, and unverified references. |
19
+ | Recurring finding across packages | Is this the same cause in more places or an unresolved seam? | Breadth: enumerate the class mechanically, rule each hit one time, and prove the owning fix in one consumer before spreading it. Depth: reproduce the actual case and ask a design question when the class recurs. § Enumerate breadth mechanically, then rule causes. |
20
+ | Review that does not converge | Does the finding falsify a claim or cross the declared release bar? | Yes: repair or explicitly rescope the claim. No: defer with a trigger. Apply the seam stop, re-audit only repaired claims, and refuse an endless tuning loop on plausible language examples. § Bound depth by claims, release consequence, and an explicit stop; § Reconcile evidence rather than reviewer votes; § Test the proposed remedy against legitimate adjacent behavior. |
21
+ | Contract or schema consumer | Is this authored policy, foreign advertisement, or declaration as data? | Authored: apply strict plus semantic validation; § Separate shape parsing, semantic admission, and authoring validation; § Convert schemas in the direction the boundary promises. Foreign: widen directionally and keep the original advertisement; § Convert schemas in the direction the boundary promises. Data: validate without compilation; § Separate shape parsing, semantic admission, and authoring validation. Requiredness and defaults: § Give defaults one owner and validate their placement. |
22
+ | Decision family | Is input missing, a check false, a factor inapplicable, or execution failed? | Preserve unread, met, and unmet states and reached input questions. Keep no-application identity apart from invalid empty authority. Keep a non-input failure undecided. § Carry unread, unmet, and non-input failures separately; § Re-derive decisions from validated answers, not editable prior results. |
23
+ | Agent or server tools | Is approval attached to the advertised object and an actual waiter? | Pin the instance and recheck after callbacks: § Keep learned proposals outside deterministic authority. Correlate on the wire and show complete arguments: § Correlate a page approval to an actual waiting call. Refuse a hang-freedom claim from a copied call's timeout. |
24
+ | Stored conversation versus wire | Who authored text, and which representation admits it? | Let a host head and the wire carry a system role, and refuse that role at owned stored ingress: § Separate authorship from data and project outward explicitly. Bind the live conversation instance and the principal store: § Bind operation identity and state mutation to admission. |
25
+ | Streaming provider | Was a complete record malformed, was a terminal missing, or did the client cut the tail? | Parse or refuse complete lines, check terminal settlement separately, and discard only client-cut fragments: § Distinguish syntax, terminal settlement, and intentional client cuts. A transport status of 200 proves only that the transport answered, and an answer and context retention each take their own proof: § Preserve failure and absence at the actual protocol boundary. |
26
+ | Provider safety transformation | Does the actual renderer interpret this carrier? | Measure fixed inputs first, then transform only established carriers, preserving own-key behavior and collision limits. § Neutralize only the carriers the renderer actually interprets. |
27
+ | Persistence or compaction | What has committed, and which marks govern resume? | Snapshot source marks after the result, preserve original logs, and state the different rollback boundaries of a plain fold and a later merge. § Preserve source history and name the real transaction boundary. |
28
+ | Instruction libraries | Is this wiring timing or a model's observed use? | Wiring timing: prove the next-run or fold effect with a scripted run; § Load instructions progressively and prove when they take effect. Observed use: run model-driven efficacy as a separate study; § Exercise the composed consumer early and match the claimed host; § Separate developmental evidence, confirmation, and answer-path quality. |
29
+ | Proof or review | Did the named assertion fail, did compilation alone fail, or did a file not run? | Keep failing-first, mutation, collection, restore, and independent receipts separate. § Prove an instrument's domain and its actual sensitivity; § Keep failing-first, mutation, restoration, and collection receipts distinct; § Reconcile evidence rather than reviewer votes. A mutant that hangs its own timer: § Use a terminating count to prove a synchronous bound. |
30
+ | Study or custody | Is the claim freeze, grade, progress, replay, or next-request identity? | Prove the exact operation or entry and its control, and refuse a successful neighbor operation as a substitute. § Prove custody and the exact closure route before expensive use. |
31
+ | Learned reader or router | Is the candidate using metadata that ships, and does its fallback win where invoked? | Remeasure the shippable intervention: § Compare the shippable intervention, including what it loses. Charge costs: § Charge a learned decision for the decision itself. Keep the written comparison graph and infer no winner from disagreement: § Keep the committed comparison graph and the meaning of each metric. A reader that changes what it extracts: § Report extraction quality alongside latency. |
32
+ | Consumer migration | Is the consumer exhaustive, defaulted, indirect, or nested? | Census all forms and execute the defaulted or loaded path: § Audit a consumer migration beyond compiling names. Prove packed and registry identity separately: § Distinguish source revision, packed bytes, registry resolution, and publication. |
33
+ | Campaign runner | Is the scope stale, the host owned, or the artifact replaced by installation? | Rebase the brief: § Rebase the effective brief before launching it. Hold inputs: § Own exact regions and hold the proof's entire input set. Bound service contacts: § Make service and data side effects explicit in the brief. Probe the runner and completion artifact: § Verify the actual runner and completion artifact. |
34
+ | Product or reuse | Does a real consumer need the mechanism or only an abandoned experiment? | Match installed semantics and promote or retire deliberately: § Promote a real shared mechanism and retire experiment residue. Keep the requested product runnable: § Keep the requested product runnable while hardening its dependencies. An authoring shorthand: § Test author comprehension and observable meaning. Prose for a reader without the campaign: § Document the shipped behavior for a reader without campaign context. |
35
+ | Evidence interface | Is the value measured, predicted, replayed, incomplete, or illustrative? | Label its actual state, clear stale predictions, and verify rendered output and one export representation. § Let an evidence interface show only observations it actually owns. |
36
+
37
+ ## Performance
38
+
39
+ ### Reuse work at its valid lifetime
40
+
41
+ When construction or lookup repeats inside the work it supports, measure the repeated term, retain its result for the operation or entity whose identity makes it valid, keep first-use costs visible, and read cold and warm as separate claims.
42
+
43
+ - **Refuse.** A cross-call cache keyed by message count or a persisted call-scoped memo, because removal and appends preserve the count and read-once semantics are limited across concurrent writes.
44
+ - **Reading.** In the `@orkestrel/contract` package at commit `0f05405`, depth-6 construction reads “1.317 to 0.111 ms”, with object checks 2–4 percent slower. This saving is not additive with any other reuse reading.
45
+ - **Example.** `@orkestrel/contract` `0f05405`: sealed shapes, so a walk of a built shape runs one time.
46
+ - **Law.** `.claude/rules/quality.md` § Performance.
47
+
48
+ ### Revert a speed-only change that misses its own acceptance
49
+
50
+ When a faster large fixture accompanies slower small consumers, set the improvement and no-regression conditions before the run, revert the helper and its call-site swaps when the no-regression condition fails or one faster cell is the only gain, record a missed improvement target as a miss, and retain the pins and bench.
51
+
52
+ - **Refuse.** Keeping a failed helper or its call-site swaps because one cell improves, because one faster large array does not override the small-consumer no-regression condition. Landing a speedup that weakens a published promise before a throwaway copy measures it, because the number must be weighed against the promise: deferring `schema` saves 4.7 of 36.6 ms on `@orkestrel/reason`, and `@orkestrel/contract` `d359d94` declines it.
53
+ - **Reading.** In the `@orkestrel/contract` package, on the bench retained at commit `09d0673`: “Small-fixture pool: 1.2061 [1.1400, 1.2760], or 20.6% slower.” The `arrayOf` ratio is 0.6843, but the `recordOf` ratio at 0.8416 misses its 20% gain target and small fixtures miss the 5% regression bound. A/A passes, so a passing instrument does not make the candidate acceptable. The percentages are this experiment's bars.
54
+ - **Example.** `@orkestrel/contract` `09d0673`: the fixed-array guard helper is reverted with no release, and the pins and bench stay.
55
+ - **Law.** `.claude/rules/quality.md` § Performance.
56
+
57
+ ### Replace copy-on-append with an appropriate queue structure
58
+
59
+ When stream buffering recopies accumulated data for each delta, replace the copies with a queue that drains, move the head before each yield so the queue retains at most one taken value and no successor chain, prove output identity, and price generation and shape cases separately.
60
+
61
+ - **Refuse.** Inferring a gain from append microtiming alone, because generation and shape cases carry their own prices.
62
+ - **Reading.** In the `@orkestrel/agent` package at commit `dd8dee79`: “1078.2 ms before, 13.2 ms after”; A slope 3.03 to 0.98 and C slope 2.58 to 1.06. Case B ratio 1.0329 stays under this run's 1.05 bar, but still pays a measured 1.9–4.7% cost. Six processes per build, A/A passes, other load at most 4.6% per process. Sensitivity spins first under-deliver, and calibration is repaired before the final comparison.
63
+ - **Example.** `@orkestrel/agent` `dd8dee79`: the `Channel` class buffers in linked cells, a structure specific to this package.
64
+
65
+ ### Own and freeze once, and price restoration separately
66
+
67
+ When repeated copies protect reads but dominate selection, copy the owned JSON, walk it with a worklist, freeze the copy so the input stays untouched, gate both repeated reads and hydrate, and state the changed mutation and aliasing behavior in upgrade guidance.
68
+
69
+ - **Refuse.** Freezing inside a reviver, because restoration is priced beside the repeated-read saving and the reviver's hydrate fails its gate.
70
+ - **Reading.** In the `@orkestrel/agent` package at commit `9745e36e`, selection reads “2136.7 → 780.5 ms”; the reviver's hydrate “52.6 → 73.7 ms” fails. Final copy/walk hydrate is 55.02 ms against 52.73/52.30 ms, ratio 1.0433. The kept slot reports equal digests and other load at most 1.7%. The 51106-judgment readings are report-only.
71
+ - **Example.** `@orkestrel/agent` `9745e36e`: the `JudgmentManager` class keeps the copy and worklist after the reviver candidate is reverted, and a host editing a snapshot judgment to migrate or redact it observes the ownership change.
72
+ - **Law.** `.claude/rules/quality.md` § Performance.
73
+
74
+ ### Yield real host turns and prove the interleavings they add
75
+
76
+ When long synchronous work blocks an interactive caller, or cheap-looking yields consume a deadline, measure host turns, deadline cost, and unscheduled throughput separately, race cancellation where a supplied scheduler can remain pending, and test source removal, stale plans, and callback cancellation.
77
+
78
+ - **Refuse.** A microtask yield as a host turn, because resolving a promise is not proof that the host serviced its next turn. Scheduling reported as a speed-only edit, because scheduling adds interleavings. A raced host yield claimed as preemption, because it does not preempt arbitrary work.
79
+ - **Reading.** In the `@orkestrel/agent` package at pacing commit `77df10c2`, the maximum heartbeat gap reads “43.83 → 23.57 ms”, and correction and control both miss this run's 12.5 ms target. The reduction is retained without moving the target. A microtask control tests whether the heartbeat instrument sees a host turn. No cross-host yield equivalence follows.
80
+ - **Example.** `@orkestrel/agent` `77df10c2`: the `Classifier` and `Ledger` classes pace long work, and commit `069540aa` repairs cancellation for that pacing.
81
+
82
+ ### Make persisted identity match the declared value semantics
83
+
84
+ When JSON persistence sorts keys and silently destroys memo hits, compare JSON values structurally, set categorical tie order explicitly, use an independent canonical-copy oracle with semantic negative controls, cover own `__proto__` and `constructor` keys with controls, and keep positional-prompt limits separate.
85
+
86
+ - **Refuse.** Storing consumer checkpoint state as opaque JSON text or changing the `@orkestrel/study` canonicalization, because real hosts still lose judgments and canonical bytes back the digests of that package. Claiming arbitrary JavaScript equality, because the comparator's domain is JSON rendering, not cyclic objects, bigint, or arbitrary `toJSON` behavior.
87
+ - **Reading.** In the `@orkestrel/agent` package at commit `a82c5985`, correction-1600 ratios are 0.915 and 0.918, and the change is retained for a predeclared correctness merit, not a speed target. Sorted-seed controls exercise the repaired path, and two quiet runs are recorded. No hydrate timing runs, because hydrate is untouched.
88
+ - **Example.** `@orkestrel/agent` `a82c5985`: the `matchesJSON` and `matchesJudgment` functions compare by value, overturning commits `c6e34379` and `f28d222e`, and the `@orkestrel/study` canonical encoding that exposes the defect stays.
89
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
90
+
91
+ ### Index against realistic text and retain small-registry costs
92
+
93
+ When each message scans an entity registry, measure an index across registry sizes and real text, prove ordered matching equivalence, and publish Unicode and host limits.
94
+
95
+ - **Refuse.** A load detector or selector added to conceal a small-fixture cost, because selection needs a free exact count, parity, and a measured sweep.
96
+ - **Reading.** In the `@orkestrel/agent` package at commit `c70e64cd`, control-1600 selection reads “131.98→59.67 ms”; real-text lookup at registry sizes A=1 and A=3 costs “+12.08 and +9.20 ms per 1600 texts”, while A=12 saves 6.88 ms. Those costs are accepted alongside scale gains. Independent Unicode controls are required, with “a browser's tables unread” as the stated limit.
97
+ - **Example.** `@orkestrel/agent` `c70e64cd`: an index replaces the per-message registry scan around the `normalizeWord` and `matchEntities` functions, whose placement at that commit is unchecked.
98
+ - **Law.** `.claude/rules/quality.md` § Performance.
99
+
100
+ ### Search a cut instead of rendering every candidate
101
+
102
+ When large text exposes repeated per-line rendering or splitting that short-message fixtures hide, count the term, search the cut, prove semantic boundaries with a pin whose accepted amendment has a cut that crosses a flip, and state the monotonicity assumption.
103
+
104
+ - **Refuse.** Inferring arbitrary-cut correctness from ordinary seed digests, because equal digests close only the measured shapes and the fitting predicate must stay monotonic in the searched region.
105
+ - **Reading.** In the `@orkestrel/agent` package at commit `275c0dab`, correction paste200 reads “3924.77→106.90 ms” and control reads “3813.59→64.82 ms”. The 200 KB correction exponent falls 2.546 to 1.185, but 53.2 ms added cost stays recorded rather than chased. The comparison departs to separate slots, with a roughly 2% resolution limit.
106
+ - **Example.** `@orkestrel/agent` `275c0dab`: the `#trim` method of the `Ledger` class searches the cut instead of rendering each candidate.
107
+
108
+ ### Close a cost question without building an optimization
109
+
110
+ When a suspected whole-set store cost has no demonstrated consumer impact, measure the actual driver and growth first, and leave the mechanism unchanged if the reading closes the question.
111
+
112
+ - **Refuse.** Extending one driver's evidence to every driver, because other drivers stay unmeasured.
113
+ - **Reading.** In the `@orkestrel/agent` package, on the memory driver: “set at 2000 revisions: 4.563 ms”; slopes set 1.025 and get 1.003. No before/after candidate is compared. The question closes for the memory driver only, using the stated quiet slot and some adjacent host readings.
114
+ - **Example.** `@orkestrel/agent` `no commit recorded`: the `MemoryMemoStore` class stays unchanged, because no optimization is required.
115
+ - **Law.** `.claude/rules/quality.md` § Performance.
116
+
117
+ ### Remove exponential work before adding a bound around it
118
+
119
+ When shared cyclic graphs repeatedly traverse the same structure, change precedence so one linear walk decides.
120
+
121
+ - **Refuse.** Bounding the old mechanism as the repair, because a guard limit alone does not justify retaining an avoidable exponential mechanism.
122
+ - **Reading.** In the `@orkestrel/contract` package at commit `aadb739`, on a shared cyclic graph: “22 levels 4.56 s to 163 µs; 41 levels 253 µs.” This reading closes the recorded cost repair, not later re-audit findings or package readiness. Host conditions and uncertainty are absent, and the bounded approach has no after-build.
123
+ - **Example.** `@orkestrel/contract` `aadb739`: the `#measure` method checks the already captured cycle before height calculation instead of taking the `#trace` path, and other files in that commit carry no attributed gain.
124
+ - **Law.** `.claude/rules/quality.md` § Performance.
125
+
126
+ ### Dispatch a union through its declared discriminant
127
+
128
+ When parsing tries arms in sequence even though a literal property identifies an arm, use that property to select the arm and retain the union's contract.
129
+
130
+ - **Refuse.** Generalizing this dispatch to nondiscriminated unions, because no literal property identifies an arm there.
131
+ - **Reading.** In the `@orkestrel/contract` package at commit `4dff475`: “Last arm 20.7 to 4.1 µs.” Other arm costs, uncertainty, and host conditions are not supplied.
132
+ - **Example.** `@orkestrel/contract` `4dff475`: a union parse selects its arm by the literal property, and this multi-purpose commit makes no claim that every changed file implements union dispatch.
133
+ - **Law.** `.claude/rules/quality.md` § Performance.
134
+
135
+ ### Enforce a bound before paying the refused work
136
+
137
+ When a validation limit is read only after ownership allocates or a parser traverses expensive input, measure each public door separately and count the loop before rewriting it.
138
+
139
+ - **Refuse.** A bound sized only from the `is` fixture, because every door pays a different prefix of work before refusal. An accepted bound claimed as repaired complexity, because the two are separate claims.
140
+ - **Reading.** In the `@orkestrel/contract` package, on the `is` fixture: “createContract spent 1.2 GB before refusal”, and the `cloneShape` function costs about eight times the `is` fixture. This reading precedes the door-bound carrier, measures no after-repair cost, and stays a separate checkpoint from readings at other doors and packages.
141
+ - **Example.** `@orkestrel/contract` `32b987b`: the door-bound carrier, with boundary proofs.
142
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
143
+
144
+ ### Price the complete route before optimizing its kernel
145
+
146
+ When a computational kernel looks faster on a worker or in another representation, separate compute, validation, and copy or freeze cost from the rest of the route, distinguish transient peak from retained memory, and compare the actual public result rather than a rounded summary.
147
+
148
+ - **Refuse.** A worker-routing recommendation without a crossover, because a router needs a measured decision boundary after all route costs. Tiny-model cost scaled per parameter, because that scaling overstates larger-model work. Removing a safety check on these readings, because no reading here authorizes that removal.
149
+ - **Reading.** In the `@orkestrel/learn` package, on the research comparison at 8 subjects and 24 factors: “Guard 1.99 ms of 2.17 ms at 8 subjects and 24 factors”; worker/inline flattens near 1.7, and all six app holdouts prefer inline. This reading is diagnostic evidence, not a landed speed repair, and host identities differ between archived and fresh runs and stay separate.
150
+ - **Example.** `@orkestrel/learn` `no commit recorded`: a diagnostic comparison that closes with no worker-routing recommendation.
151
+ - **Law.** `.claude/rules/quality.md` § Performance.
152
+
153
+ ## Measurement
154
+
155
+ ### Calibrate the comparison, not merely the timer
156
+
157
+ When a timing claim sits near noise, timer resolution, or another host's absolute bar, define the marked region, warm it, add a calibrated delivered slowdown beside the interleaved comparison, report process-level uncertainty, preserve semantic digests, and record a missed target apart from a failed keep boundary.
158
+
159
+ - **Refuse.** Profiler shares, whole callback time, or a nominal spin as the gate wall, because timer quantization and work outside the mark move the reading and CPU resolution could exceed the short measured region. Forced collection for timing or an under-delivered spin as a control, because a control's delivered effect and its interference must be measured. A fixed sample count, because no universal sample count follows. A campaign's earlier build quoted as the published baseline, because the `@orkestrel/reason` hardened-build import at 93.3 ms is not the published artifact, recorded as 19.44 ms at commit `f8646a5`.
160
+ - **Reading.** In the `@orkestrel/contract` package at commit `32b987b`, on the `@orkestrel/reason` build: a loaded-host reading of 37.57 ms against 35 ms, while interleaved readings of 35.78/36.68 ms attribute 0.9 ms (2.5%) to the change. Counts and bars are run-specific. The `c_diff` expression is a derivation, not a cited formula, and external timing and statistical references stay untraced.
161
+ - **Example.** `@orkestrel/contract` `32b987b`: the repair carrier of the door bound, whose interleaved comparison separates the change from host load, and the scratch comparison drivers sit outside that commit.
162
+ - **Law.** `.claude/rules/quality.md` § Performance.
163
+
164
+ ### Derive the performance stop from the consumer
165
+
166
+ When an optimization lacks an economic stopping point, price hydrate through first selection against measured model time, include message bytes and real text beside the count, and reopen deferred work on its explicit consumer-cost trigger.
167
+
168
+ - **Refuse.** A budget taken from an unmeasured model call, because the stop derives from measured model time. A count-only load, because message bytes carry a cost that the count hides. A retroactive slope bar on held share-only work, because a bar belongs to the run that set it.
169
+ - **Reading.** In the `@orkestrel/agent` package, on the measured 4B call: “660 ms derives from 5% of 13206 ms, rounded from 660.3 ms.” The real 290-message selection reads 62.47 ms. The cross-call projection closes unbuilt, reopening above 10% of consumer model time to first token. The 660 ms budget comes from the measured 4B call, not an unmeasured 2B call, and the 5% and 10% figures belong to this run.
170
+ - **Example.** `@orkestrel/agent` `no commit recorded`: the stop decision around the `Ledger` class request and select path holds share-only work and changes no implementation.
171
+ - **Law.** `.claude/rules/quality.md` § Performance.
172
+
173
+ ### Separate model perturbation from cache-identity changes
174
+
175
+ When repeat or sham arms are supposed to measure noise, check whether the perturbed parameter also keys persisted judgments, account for warming on a nongate goal, preserve raw spend, compare only within a sealed lineage, open another lineage when the instrument changes, record an unreached stratum as unreached, and disclose an after-data exception with its beneficiary and owner ruling.
176
+
177
+ - **Refuse.** A changed seed read as pure noise, because sampling parameters can also be cache identity. A heuristic subtraction of re-asks, because the `Earlier message:` subtraction misses pair cases. A quality gate as proof that a cap loses nothing, because a quality gate that cannot see missing filings cannot certify that cap. A floored instrument read as a loss or a keep, because a floored instrument shows no gain and measures no loss. A substitute arm for an unreached stratum, because a reachable stratum on another arm answers a different question. An after-data exception read as a standing rule, because that exception rewrites no future gate.
178
+ - **Reading.** In the `@orkestrel/agent` package, on the repeat arm of the memory study: “Repeat re-asked 184 held judgments, 243.1 s.” This reading stays a separate checkpoint from the burst readings and compares with none of them as one experiment. No single commit closes the perturbation and lineage observations, and external nondeterminism and cache sources stay untraced.
179
+ - **Example.** `@orkestrel/agent` `1a29fcf1`: the `LedgerCorrectionOptions.narrow` option stays at default false, and its topic-only and free-text missed-case limit stays specific to this package.
180
+
181
+ ### Size runs from observed work and preserve failed-run accounting
182
+
183
+ When model runs or labelers threaten to consume a cap before producing inspectable evidence, project from measured wall, model seconds, growth, and launch overhead, use short sealed segments, retain each arm, revise by lineage, charge unsealed work manually, state absent terminal accounting and an unread grade after a valid seal, and diagnose profile admission separately from package defects.
184
+
185
+ - **Refuse.** Raising only a byte bound, because that raise renames the failure and leaves completion unaddressed, so give each repair its own failing receipt. A calibration observation as a profile policy, because a calibration observation is not a conservative admission setting. A shaped proxy reply as replay, because a shaped proxy reply is not exact replay.
186
+ - **Reading.** In the `@orkestrel/agent` package, on the memory study: goals 1–24 consume 711.7 s, the checkpoint holds 318725 bytes with 9.4–9.9 KB growth per goal, and launch adds 17–19 s. These readings are internal measurements with no external bibliography traced, and no single corrective commit belongs to them.
187
+ - **Example.** `@orkestrel/agent` `no commit recorded`: “A profile value stopped the compaction arm, not a defect in Agent or Study”, and no successful fold comparison follows from that stopped arm.
188
+ - **Law.** `.agents/orchestration.md` § Hold the plan.
189
+
190
+ ### Charge a learned decision for the decision itself
191
+
192
+ When a learned router beats a threshold in prediction quality, check semantic permission before cost selection, compare paired regret and accuracy with threshold and fixed routes, repeat fresh sessions and out-of-range populations, test a unit-invariant target with controls that challenge the objective, and state which comparisons are predeclared.
193
+
194
+ - **Refuse.** Accuracy alone as net gain, or a cheap job as economically suitable, because a decision is charged against the saving that decision can earn. A shuffled control on a population whose fixed winner is already perfect, because that control challenges no objective.
195
+ - **Reading.** In the `@orkestrel/learn` package, on the head-to-head research comparison: “dense* saves about 62 µs versus threshold on 255 µs topk, warm cost 8.2 µs.” The counting job costs 7.7 µs, less than the policy. No universal policy winner or deployment recommendation follows, and this research protocol stands on a supplied summary.
196
+ - **Example.** `@orkestrel/learn` `no commit recorded`: natural-log targets test unit invariance, with heldout populations and fresh-session load recorded.
197
+ - **Law.** `.claude/rules/quality.md` § Performance.
198
+
199
+ ### Separate numeric bytes, predictions, and decisions
200
+
201
+ When a fit is claimed portable across hosts, compare artifact coefficients, raw predictions, and actual decisions independently, and disclose untested engines and close-margin limits.
202
+
203
+ - **Refuse.** Byte determinism inferred from identical decisions, because artifact equality, numeric closeness, and decision agreement are different claims. Rejecting the observed routing agreement along with byte identity, because the rejected claim is cross-host byte identity alone.
204
+ - **Reading.** In the `@orkestrel/learn` package, on Node 26 and Chromium 156 on Windows: “55 of 57 coefficients differ”; 8482/49152 predictions differ at most 1.8e-15; “0 of 24576 route flips.” Same-host fits repeat, cross-host byte identity fails, and the tested decision grid agrees. Firefox and WebKit stay unread, no near-tie assurance follows, and the external numeric explanation stays unverified.
205
+ - **Example.** `@orkestrel/learn` `9ba461c`: a recorded outcome and tie-handling carrier, not a repair of cross-host floating-point identity.
206
+
207
+ ### Report extraction quality alongside latency
208
+
209
+ When a reader meets or misses a latency objective while changing what it extracts, price selection, field filling, validation, and model size, count accepted and latent wrong fields, follow answers through the decision, and score the actual consumer instance across independent state sequences.
210
+
211
+ - **Refuse.** A faster reader called correct, or a larger reader called within budget, because latent wrong values remain behind a zero silent count. Fresh-instance scoring, because fresh-instance scoring misses carryover in a reused interpreter. A definition-validation ceiling stated as measured, because that ceiling stays proposed until a built fixture measures it.
212
+ - **Reading.** In the `@orkestrel/learn` package, on the reader research: richer names raise right choices from 1017 to 1155/1200 while choice cost rises about 510 to 665 ms. Primary research stays unread for this reading, and no external claim is added to it.
213
+ - **Example.** `@orkestrel/interpret` `5104318`: latent-field accounting, a change distinct from the latency observations.
214
+
215
+ ### Keep operational evidence in its own category
216
+
217
+ When a gate duration, scan memory, transfer size, corpus runtime, or ceiling is cited as a product gain, record the measurement for capacity planning, claim only its actual subject, and keep durations distinct from allowances.
218
+
219
+ - **Refuse.** An operational figure cited as a source speedup, because these figures establish no attributed source speedup. A cap read as a measured duration, because a cap is an allowance.
220
+ - **Reading.** In the `@orkestrel/study` package, on its suite: “Study suite 109910 ms against 109479 ms”. This figure establishes no attributed source speedup.
221
+ - **Example.** `@orkestrel/study` `no commit recorded`: a context-only record with no optimization carrier, where nothing is reverted because no speed repair is established.
222
+
223
+ ### Keep the committed comparison graph and the meaning of each metric
224
+
225
+ When a comparison has a written pairwise graph, select by that graph, preserve post-hoc comparisons as post hoc, inspect population contributions and tails, compare any fallback on the cases it would receive, and separate retention from continuation, raw byte stability from semantics, and deterministic criteria from statistical stopping.
226
+
227
+ - **Refuse.** A winner inferred from disagreement, because a disagreement signal can support refusal without selecting the right answer. Continuation inferred from retention, because “Retaining relevant information does not by itself yield successful continuation”. A model-option pin that departs from an effective default, because a pin must repeat effective defaults and introduce no hidden experiment. An unrecorded override of a keep rule that loses on a metric overstating the cost, because that override stands on the record with its reason and a re-read rule. A scorer difference ruled after the run, because a ruling after the run has outcomes in view, so run both scorers on scripted traces before any outcome exists.
228
+ - **Reading.** In the `@orkestrel/learn` package at commit `2f598bf`, on the head-to-head selection graph: “That chain never compares `blend` with `dense*`”, and the fallback loses on flagged populations. For the distinctions, see the recorded [continuation study](https://arxiv.org/html/2610.31710v2) and [conformal overview](https://arxiv.org/abs/2107.07511). Neither link is independently validated, and no confidence monotonicity theorem or calibration result follows from them.
229
+ - **Example.** `@orkestrel/learn` `2f598bf`: the written lead-arm rule selects the `blend` arm, and the direct `blend` and `dense*` comparisons stay post hoc and unrouted.
230
+
231
+ ### Compare the shippable intervention, including what it loses
232
+
233
+ When copying, quotes, aliases, units, field kinds, or reader size is proposed as a treatment, evaluate each as a different intervention, run with only metadata the public contract carries, set the keep rule as a cost ratio before the column runs, retain latent errors and lost right answers, and inspect shared brief vocabulary in purported holdouts.
234
+
235
+ - **Refuse.** Usage frequency as counterfactual benefit, because a usage count measures wording, not value. An additive oracle as the replacement fitted method, because the two are different interventions. Field descriptions fitted from the writers' own brief, or fitted synonyms, called independent generalization, because writers who share descriptions share vocabulary, so quote only blind readings. Filling fields by a model's index links or quoted evidence, because index links add silent errors and quoting costs more right answers than the wrong answers it removes. Unit lists through alias channels, because units collide. A provider's need for prompt teaching of structured-output descriptions generalized to every provider, because that behavior is recorded on one provider.
236
+ - **Reading.** In the `@orkestrel/learn` package, on the reader research quote-field intervention: quote fields remove six accepted wrongs but cost 99 right answers and raise latent errors.
237
+ - **Example.** `@orkestrel/learn` `7dbde07`: the fitted experiment, where “Both writers saw the same field descriptions and task”, shared-vocabulary word removal overcorrects, and the true fitted benefit stays unidentified, not proven zero.
238
+
239
+ ### Preserve research provenance, qualifications, and unverified references
240
+
241
+ When a claim carries a verifier's wording, a vendor or external source, or an unresolved citation, carry the corrected wording and source generation, mark vendor claims and proposals apart from measured project results, retain unresolved citation tokens, and hold a quote from a supplied record as a record claim until separately verified.
242
+
243
+ - **Refuse.** An invented link in place of an unresolved citation, because a citation with no resolvable locator stays unresolved on the record. An external benchmark inherited as a project result, because external work motivates a comparison, not a predetermined winner or an inherited benchmark result. A reworded verifier correction, because “A partly confirmed claim appears as corrected; use no other wording of it”. A corpus table a writer reports recorded without an independent rescore, because a supplied record remains a record claim until separately verified.
244
+ - **Reading.** In the `@orkestrel/learn` package, on the unresolved citation tokens of its research source list: “They were not silently replaced with invented references”. Source-specific limits stay attached: vendor summaries, abstract-only results, unpinned upstream code, and no project reproduction. The recorded citations are not freshly fetched or independently validated.
245
+ - **Example.** `@orkestrel/learn` `87a6463`: a historical source record, where a citation token with no resolvable external locator stays unresolved.
246
+ - **Law.** `.claude/rules/quality.md` § Evidence before change.
247
+
248
+ ## Boundaries and refusal
249
+
250
+ ### Choose validation by frequency and representation
251
+
252
+ When contract adoption threatens to multiply per-element validation cost, select each guard as the law fixes, bind every hand guard to a representation-specific law, and read an open foreign interface apart from an owned exact record.
253
+
254
+ - **Refuse.** Mechanical contract conversion in every element path, because the guards multiply per-element cost. Universal guard and contract equality, because definitions, runtime results, wire projections, and owned snapshots need different implications.
255
+ - **Reading.** In the `@orkestrel/agent` package, at the measured hoist commit `b9532a1b`, the correction hydrate reads 1770.78 ms, with contract guards adding about 2.4 s. The relay per-frame bar below 50 µs is a bar that policy names, not an observed gain for every guard.
256
+ - **Example.** `@orkestrel/agent` `b9532a1b`: the measured hoist carrier for the hydrate, memo, and message guards, with no universal guard replacement commit claimed.
257
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
258
+
259
+ ### State the representation before choosing exactness
260
+
261
+ When a guard and its contract disagree, or exactness is about to be chosen, name the representation first: a definition needs its `is` method to imply the guard, a runtime result keeps its runtime values and passes the `wire.is(project(result))` check on its projected wire form, a runtime guard stays wider, and a manager's owned snapshot and a raw store's retained reference stay different contracts.
262
+
263
+ - **Refuse.** Tightening every guard to JSON, because that rejects valid runtime NaN and host values. A frozen-identity claim beyond stored records, because a derived return can be “a fresh unfrozen sum when several do”.
264
+ - **Reading.** Across the recorded guard and contract splits: “Tightening runtime guards would have been wrong for most splits”. No general snapshot-migration commit is supplied.
265
+ - **Example.** `@orkestrel/agent` `c1306929`: owned memo copies, with the store value-equality clarification carried apart at `dc7059e4`.
266
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal and § Foreign contracts.
267
+
268
+ ### Separate shape parsing, semantic admission, and authoring validation
269
+
270
+ When a value moves through a parser, a semantic door, or an authoring definition, make the semantic door explain, reject extras, saturation, and ambiguous repair, parse, and admit only lossless repairs with recorded changes, give an authoring definition deep validation of arity, references, cycles, and collisions, and let compilation own validating defaults, because a declaration supplied as data can be valid without being compilable.
271
+
272
+ - **Refuse.** A parse or an `explain` result treated as admission, because a parser can coerce without preserving meaning. A second recursive shape grammar, bounded grammar expansion, JSON-refinement exclusion of a `RegExp` value, and guard-only composition, with no reason recorded.
273
+ - **Reading.** On the input `{amount:'500'}`: “an object union parses `{amount:'500'}` to `{}`”, and integer rounding, underflow, and unknown fields remain. Public deep-schema authoring and the recursive `$defs` keyword remain conditional, not implemented research results.
274
+ - **Example.** `@orkestrel/contract` `aadb739`: the `shapeShape` declaration and the `ContractCompiler` class, under the recorded statement “Validation and compilation stay apart”, with no universal semantic-admission commit recorded.
275
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
276
+
277
+ ### Convert schemas in the direction the boundary promises
278
+
279
+ When a schema converts for an authored decision definition or a remote advertisement, convert the authored definition strictly, widen the remote advertisement leniently where unsupported constraints cannot be represented while preserving the original schema, compile owned declarations at construction, defer foreign conversion to first use with an explicit raw opt-out, and give the `patternProperties` keyword, prefix items, nullable enums, and unsupported keywords directional cases.
280
+
281
+ - **Refuse.** Exactly-one semantics after widening indistinguishable arms, because the widened arms cannot be told apart. Owned-schema strictness imposed silently on a remote tool, because that makes the remote tool uncallable. A universal strict statement, because authored boundaries and remote advertisements have opposite approximation obligations.
282
+ - **Reading.** In the `@orkestrel/contract` package, `no commit recorded`, on the foreign conversion cases: “23 of 58 rows refuse or change the value”. No single landing commit is supplied, so implementation stays prescribed where no later receipt supplies one.
283
+ - **Example.** `@orkestrel/contract` `no commit recorded`: the `SchemaShaper` class changes a lenient `oneOf` keyword to a union, and `@orkestrel/mcp` descriptors and `@orkestrel/agent` run schemas consume it.
284
+
285
+ ### Give defaults one owner and validate their placement
286
+
287
+ When a shape carries requiredness and defaults through cloning and filling, keep both in the shape, validate and freeze the defaults, preserve them through cloning, return a fresh filled tree, and derive filled paths from input and output.
288
+
289
+ - **Refuse.** A parallel recipe default or a silently filled required input, because the shape owns defaults and their legal placement. A default where union identity or open-object behavior can skip or conceal it, because the misspelled `{licenced:false}` input fills the `licensed:true` value with empty audit and explain output.
290
+ - **Reading.** In the `@orkestrel/contract` package, on the `ShapeCloner` class's `#captureWrapper` method: “so without this every default vanishes silently”. This reading is a default-placement contract, not permission to manufacture missing observations. Required and default semantics stay package-specific, and `AGENTS.md` § Design laws governs `null`. The record names no single carrier.
291
+ - **Example.** `@orkestrel/interpret` `no commit recorded`: shape-owned declarations replace the `EntityMapping.required` field, the `Recipe.defaults` field, and the `FieldDefault` type.
292
+
293
+ ### Carry unread, unmet, and non-input failures separately
294
+
295
+ When a decision family can meet unread input, a false check, an inapplicable factor, or a non-input failure, close only enabled-rule conclusion keys in the supported definition, use typed operands even after a broad shape door, compare forward and backward answers without demanding identical diagnostic traces, ask only for reached input faults, and return undecided reasons for limits, non-input failures, and none-of-these selection.
296
+
297
+ - **Refuse.** Reading a missing value as false, because missing credit approves. One outcome for every empty case, because an empty authored authority differs from no applicable factors. The earlier differing-types equality rule, because a typed mismatch reads unread.
298
+ - **Reading.** “An unread input is never a value”, against the recorded failure in which missing credit approved. Partial aggregates and missing or stringified partition keys remain audit findings, not closed repairs, and a success-flag and error-list contradiction stays unresolved by its source.
299
+ - **Example.** `@orkestrel/reason` `3b2366d`: a member of the decision family that carries unread input apart from a false check.
300
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
301
+
302
+ ### Keep learned proposals outside deterministic authority
303
+
304
+ When a learned proposal, a structurally supplied authority, or a cost estimate can reach a tool call, require explicit tool authority and fallback at construction, enforce the consequential floor in the loop even for a structurally supplied authority, admit only explicit approval of the registered instance advertised for that turn, and preserve call order when parallel execution settles out of order.
305
+
306
+ - **Refuse.** A replacement that inherits another instance's approval, because authorization binds the object that executes after all callbacks. A cost estimate as permission, because “A cost estimate supplies no evidence that two operations are interchangeable.”
307
+ - **Reading.** In the `@orkestrel/agent` package, a replacement ran while the original did not, and a deny callback reopened the window. Mutations are the closing evidence of the final follow-up.
308
+ - **Example.** `@orkestrel/agent` `064ffb1d`: the `Agent#authorize`, `Agent#approve`, and `Agent#confirm` methods hold the authority path.
309
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
310
+
311
+ ### Correlate a page approval to an actual waiting call
312
+
313
+ When a page approval must reach a waiting call, let the waiting approver own the frame and the minted reply capability, keyed by the actual call object, require visible approver configuration, provide a stable detached `ask` function, show complete encoded arguments before execution, protect prompt and answer routes before body or upstream access, and abort the run directly when a response parks waiting for approval.
314
+
315
+ - **Refuse.** First-in, first-out (FIFO) order, provider IDs, loop-minted IDs, and copied-context wrappers, because a frame for an auto-approved call A appears while call B waits, and a frame represents a real pending approver entry. A no-hang claim for a copied call, because “It fails closed and never answers the wrong call, but it is held until the timeout.” Clipped arguments, because “Clipping would hide what is approved”.
316
+ - **Reading.** In the `@orkestrel/ollama` package at commit `dc5b77e`, on the page proof: the first `executed` count must read 0, the answer 204, and a duplicate answer 404. Live asks do not implement durable pause or resume.
317
+ - **Example.** `@orkestrel/agent` `dd8dee79`: the `Approver` symbol holds the pending entry behind each frame, and the `renderArguments` function renders the arguments the page shows.
318
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
319
+
320
+ ### Separate authorship from data and project outward explicitly
321
+
322
+ When text reaches an owned inlet or a relay, place host-authored instructions in privileged context and keep records, model memo descriptions, and workspace data outside it, refuse stored system roles at every owned inlet while retaining wire types that represent a built head, make a relay check head and tool definitions against server-owned wire projections, forward admitted copies in client order, and report all refusals without echoing sensitive contents, and project run frames from explicit members with chunks drained before terminal output.
323
+
324
+ - **Refuse.** Silent server replacement, because “it hides version skew”. Relay protection of the system head alone, because the renderer places tool definitions in the system turn.
325
+ - **Reading.** In the `@orkestrel/agent` package, the `plantedReachesSystem` flag reads false, which does not prove general secrecy, and a user-context heading imitation is not system elevation. A host structural `view()` method and custom renderers retain explicit trusted limits.
326
+ - **Example.** `@orkestrel/agent` `7d335a97`: the `AgentContext#build` method and the `buildRelayRequest` function, with `@orkestrel/ollama` and `@orkestrel/mcp` consuming the relay policy.
327
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
328
+
329
+ ### Bind operation identity and state mutation to admission
330
+
331
+ When a run starts, switches, or appends on a conversation, capture the conversation instance at run entry, use principal-scoped durable identity, let a guarded run start append after validation, deadline, and overlap checks, let a switch select a later run's default, and await actual run settlement before another run, because an observed request alone is not settlement.
332
+
333
+ - **Refuse.** A guard on switching, because binding preserves switching. A fresh `Agent` instance per request, because that makes overlap tests unreachable. Automatic erasure of a tail, because erasure could remove “an ask whose partial answer the page might already show.” An HTTP or session abstraction in core, because this repair earns none.
334
+ - **Reading.** In the `@orkestrel/agent` package, a guarded refusal promises “the thread unchanged and nothing started or emitted”. The malformed-signal-after-append exception and the instance-local rather than global thread lease remain documented limits.
335
+ - **Example.** `@orkestrel/agent` `e773887b`: the `AgentRunOptions.prompt` option and the `AgentContext` class bind a run to its conversation at entry.
336
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
337
+
338
+ ### Distinguish syntax, terminal settlement, and intentional client cuts
339
+
340
+ When a stream can hold an incomplete chunk, an invalid complete record, a missing terminal, or a client-cut tail, use the owning newline-delimited JSON parser, tell incomplete chunks from invalid complete records, clear on refusal, flush at normal end of file, translate only at framing seams while preserving package errors, original cause, and abort precedence, require terminal protocol evidence separately, and make byte order mark fixtures reach the parser after decoder stripping.
341
+
342
+ - **Refuse.** Syntax strictness as completion, because valid lines without a terminal still end. A flushed client-cut tail, because “a client abort can cut a record mid-line, which is no line a daemon emitted”. That discard on an ordinary end of file, because only a client-caused cut earns the exception.
343
+ - **Reading.** “a stream that ends with neither a settled result nor a terminal record throws”. Old strict framing still admits missing-done and in-band errors, later policy prescribes their separate refusal with no retroactive inclusion in the earlier release, and strictness defaults change over the history, so source timestamps matter.
344
+ - **Example.** `@orkestrel/ndjson` `4b8d736`: the `NDJSONParser` class, with the protocol-terminal follow-up separate from the earlier parser acceptance.
345
+
346
+ ### Preserve failure and absence at the actual protocol boundary
347
+
348
+ When a protocol boundary receives usage, tool output, a load response, custody, or a JSON-RPC message, preserve absent usage as an `undefined` value where the contract estimates it, route JSON-RPC request errors apart from tool execution errors, and validate successful declared outputs while preserving legitimate content fallback and tool errors.
349
+
350
+ - **Refuse.** Malformed present usage as an estimate, unrenderable tool output as a plausible string, a load-only response as an answer, or corrupt custody as running state, because each boundary preserves its failure or absence rather than inventing a value. An answer to a response, because “JSON-RPC gives no response to a response.”
351
+ - **Reading.** In the `@orkestrel/ollama` package, `no commit recorded`, on a load-only response: “HTTP 200, `done_reason: 'load'`, empty content, no error”. No single closing commit is supplied for this successor prescription.
352
+ - **Example.** `@orkestrel/mcp` `no commit recorded`: JSON-RPC request errors stay apart from tool execution errors, and a response receives no response.
353
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
354
+
355
+ ### Make refusal text corrective without pretending to know intent
356
+
357
+ When a stage refuses and its text can reach a model or a host, give a model-facing failure a fixed status-first note with a next action and no argument echo, keep the host diagnostic separate, give ingress and hydrate different remedies, and encode each untrusted identifier according to the encoder's actual promise.
358
+
359
+ - **Refuse.** A claim that encoded text contains none of its original letters, because the encoder promises “no newline and no raw call name”. Blame on a human for an automated refusal, with no reason recorded.
360
+ - **Reading.** In the `@orkestrel/interpret` package at commit `377f933`: “No decision moved: every per-case outcome and traced digest matches the last column”.
361
+ - **Example.** `@orkestrel/agent` `23d8c6c2`: the `denyCall` function and the `AUTHORITY_NOTES` constant give the model a fixed note, and host-authored rule reasons still reach the model verbatim.
362
+ - **Law.** `.claude/rules/documentation.md` § Agent-facing surfaces.
363
+
364
+ ### Neutralize only the carriers the renderer actually interprets
365
+
366
+ When a provider transform might rewrite a carrier, inspect the wire projection, renderer, and template, hold irrelevant inputs fixed while comparing raw and escaped carriers, keep provider-specific and model-specific transforms out of the generic `@orkestrel/agent` core, keep stored originals intact, preserve own-key behavior and unchanged non-target bytes, and state collision and replay limits.
367
+
368
+ - **Refuse.** Escaping every nested value, because a fixed-prefix rerun overturns the confounded carrier result. A full-vocabulary promise, because the proof tests one token.
369
+ - **Reading.** In the `@orkestrel/ollama` package at commit `dc5b77e`: the initial carrier table is confounded because “its digit prefix varied in length”, and the corrected readings remove encode changes and nested recursion. The transform is not injective, so preescaped and raw keys can collapse with last-wins behavior. The source citation is Ollama v0.40.13 and the live corrected reading is 0.40.14, and the versions stay separate. One token on one model does not establish the whole vocabulary or a behavior promise.
370
+ - **Example.** `@orkestrel/ollama` `dc5b77e`: the `mapMessages` function transforms content, call names, top-level keys, and strings, and leaves nested values and tool definitions unchanged after measured renderer evidence.
371
+
372
+ ### Preserve source history and name the real transaction boundary
373
+
374
+ When records, revisions, snapshots, or folds come from a log, derive them from the authoritative log, include the marks that determine continuation in each snapshot, capture only after a result with no outstanding request, prove caller configuration precedence, append changed memo revisions, make an unchanged value re-add inert, let deletion remove private history, and refuse blank or non-string summaries before the relevant commit.
375
+
376
+ - **Refuse.** A promise that a capped-merge refusal rolls back a fold, because the refusal arrives after the fold commits. Conflict-free replicated data type or graph machinery for one writer, because none of the recorded research requires it for the one writer in `@orkestrel/agent`.
377
+ - **Reading.** In the `@orkestrel/agent` package, on a capped merge: “the merge refusal keeps the committed fold”. Cross-pass memo changes can remain unpriced under the freshness ruling, a deferred issue that snapshots do not solve.
378
+ - **Example.** `@orkestrel/agent` `069540aa`: the `requireSummary` repair refuses a blank or non-string summary before the relevant commit.
379
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
380
+
381
+ ### Load instructions progressively and prove when they take effect
382
+
383
+ When instructions sit behind an index and demand-loaded bodies, keep the indexes short with a real loader, send host skills into instruction state rather than a tool-result evidence channel, keep model memos as data, keep stores out of the active rendered workspace, scope memo IDs by principal, price the actual built request including images, state the actual next-run or fold timing and cancellation limits, and prove activation with a scripted run apart from a model-driven efficacy study.
384
+
385
+ - **Refuse.** An index alone, because “an index with no loader tool is inert for the model”. A scripted skill study as uptake or ordering evidence, because the scripted driver has no model. A fleet-wide module-count limit, a shared index ceiling, or background consolidation, because the recorded research motivates progressive disclosure only and no consumer earns these.
386
+ - **Reading.** In the `@orkestrel/agent` package, on the scripted context study: a no-fold turn carries the acknowledgement, and the body arrives at the next run. The scripted study does not prove memo order or load rate.
387
+ - **Example.** `@orkestrel/agent` `4d897eec`: the timing study of skill bodies, with `@orkestrel/toolbox` owning the later model-driven loader.
388
+
389
+ ### Admit a declared numeric language instead of listing bad spellings
390
+
391
+ When each review finds another form a reader misreads, consume the whole declared numeric token or report it unreadable, keep no part of it, admit its declared neighbors, table-test every form of the class and both sides of the number, stop word-meaning tuning at the agreed boundary, reopen only for a class of wrong decisions through the complete model, and move a finding about what a word means to the known-limits list with its example while the reader reports why it refused.
392
+
393
+ - **Refuse.** A case-by-case refusal list, because a list of what is wrong has no end. A review's list as the proof, because `@orkestrel/interpret` reads the `3 000 000` form as 3 and the composed `@orkestrel/learn` model approves it past the authority, `no commit recorded`. A rival superseded value substituted for unreadable evidence, with no reason recorded.
394
+ - **Reading.** In the `@orkestrel/interpret` package at commit `cb0bb5c`: “20 groups of rules became 2”, and on the 1200-message corpus the right count reads 35→33 and latent 68→24. “The corpora could not see these rows”, so independent form fixtures justify a repair when corpus totals stay flat. Whole-form safety is distinct from unit semantics, aliases, and later learning, and the `my 401k` phrase remains a stated limit.
395
+ - **Example.** `@orkestrel/interpret` `cb0bb5c`: two admitted-form laws remove the unlisted `$38.50 an hour` form that dominated wrong fields, with no claim that all later language examples are repaired.
396
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
397
+
398
+ ### Re-derive decisions from validated answers, not editable prior results
399
+
400
+ When a browser holds an asked outcome or another editable prior result, treat it as untrusted JSON, validate the answers, derive the decision again from the original message and the admitted answers, keep a model as proposer, test evidence binding separately from typing, refuse or ask on disagreement, keep the reader in a host adapter rather than a provider-dependent core, and keep the asynchronous API from the first milestone when a later reader is asynchronous.
401
+
402
+ - **Refuse.** A historical immutable outcome as trusted answer input, because browser-held values are editable. Scoring on fresh instances alone, because fresh instances miss the carried `years:5` value. A synchronous call at the first milestone, because the call returns a promise from that milestone or breaks at the next. Another value substituted on disagreement, with no reason recorded.
403
+ - **Reading.** In the `@orkestrel/learn` package, on the `decide` and `answer` routes: “An edited value in it cannot decide anything”. In the `@orkestrel/interpret` package, default history 0 at commit `f65b39e` fixes the independent-message contract, not every stateful use.
404
+ - **Example.** `@orkestrel/learn` `2f95714`: the accepted first milestone, against the failed baseline at `507e759`.
405
+ - **Law.** `.claude/rules/patterns.md` § Admission and refusal.
406
+
407
+ ## Proofs and tests
408
+
409
+ ### Use a terminating count to prove a synchronous bound
410
+
411
+ When disabling a synchronous guard makes its mutation nonterminating, size the bounded fixture the law names to finish in both states, and confirm collection, expected red, restoration, and green as separate steps.
412
+
413
+ - **Refuse.** A same-thread test timeout as the stop, because the blocked thread owns that timer. An uncollected suite or an import failure as closure of the mutation, because a terminating mutant still needs a collected named failure and an actual restored green.
414
+ - **Reading.** In the `@orkestrel/reason` package at commit `cb76b97`: “ownKeys 3 against 0; tower 32,767 visits against 10,000; prior mutants hung at 600 s and 120 s.” This reading is a committed proof repair, not evidence that a same-thread timeout interrupts synchronous work. The count stays a recorded reading, the commit establishes the test locators, and no external source is traced.
415
+ - **Example.** `@orkestrel/reason` `cb76b97`: a `Proxy` object that counts and a finite tower replace the hanging mutants.
416
+ - **Law.** `.claude/rules/tests.md` § Test contract.
417
+
418
+ ### Prove an instrument's domain and its actual sensitivity
419
+
420
+ When an instrument proves a claim, name the claim's input population, a control that reaches the relevant path, and the exact assertion that control changes, keep stable-value algebraic laws apart from accessor, reentrancy, and limit claims, and represent every public door in a local directional parity table of positive cases, negative controls, generated values, and actual producers.
421
+
422
+ - **Refuse.** An unstable-accessor control for stable laws, because that control sits outside the laws' stable-read domain. A control that moves no count, because “a one-goal widening changes no control count” and a removed guard can still throw through a later branch. A runner's successful outer exit as proof, because each claimed population needs an assertion shown able to fail. A sampled inventory read as exhaustive, because sampled barrels leave “exhaustive parity is UNRESOLVED”. Agreement across calls on a value whose reads change, because a stable-value corpus does not close a temporal claim, which asserts what one captured result promises. A limit claim read from a stable-law corpus, because a limit claim takes its own probe at field level of a value both sides accept, long, deep, self-referencing, and wide, and that probe stays blind to shared-reference graphs.
423
+ - **Reading.** In the `@orkestrel/contract` package at commit `aadb739`: generated 49722 pairs on stable values. A stable-value corpus does not close accessor or reentrancy claims, and no one carrier proves every door or temporal domain.
424
+ - **Example.** `@orkestrel/reason` `578473b`: the `auditFaultShape` parity moves to `@orkestrel/contract`, and this commit removes the local duplicate.
425
+ - **Law.** `.claude/rules/quality.md` § Instruments.
426
+
427
+ ### Keep failing-first, mutation, restoration, and collection receipts distinct
428
+
429
+ When a receipt closes a failing-first, mutation, restoration, or collection step, record the command, input, and exit for the original failure and the restored result, read named test counts and edit-file validity, and state a substitute instrument and its limits when that instrument closes a different proof.
430
+
431
+ - **Refuse.** A compilation refusal, an uncollected suite, or an unused mutation file as behavioral red, because an invalid edit never runs the case, as in “the ids probe never ran”. A mutation's outer exit as failing-first proof, because cases can be “passing on its first correct run with no failing-first receipt”. A stand-in for a missing receipt, because a missing receipt has no substitute locator.
432
+ - **Reading.** In the `@orkestrel/learn` package, an archive “does not contain the restored-run summary”. That restored run stays missing.
433
+ - **Example.** `@orkestrel/agent` `930ed86d`: per-case negative `tsc` projects substitute for absent `prove` tooling, without claiming tool equivalence.
434
+ - **Law.** `.claude/rules/tests.md` § Test contract.
435
+
436
+ ### Exercise the composed consumer early and match the claimed host
437
+
438
+ When a composed claim names a host or a review is about to deepen, run the consumer the law fixes before that review, use live services for foreign behavior, real browsers for browser claims, and protocol-faithful scripted sequences for malformed and order controls that a successful live trace cannot distinguish, and keep Node proxy, scripted mechanism, and model behavior receipts separate.
439
+
440
+ - **Refuse.** A valid live trace as malformed-input or text-safety proof, because a lenient parser and an `innerHTML` mutation can pass live valid data. A repeated tool-call response, because the repeat creates an unanswered second ask. A blind retry after failure conditions change, because altered failure conditions require a successor. A no-sampling tool call read as a wire failure, because that call can be a clean model miss. An audit or a review read as composed proof, because the `@orkestrel/learn` skeleton finds state carry after reviews.
441
+ - **Reading.** On live valid frames: “could not fail on a lenient parser, a skipped frame check, or an `innerHTML` write”, and a scripted `<b>x</b>` input and mutations supply the sensitivity.
442
+ - **Example.** `@orkestrel/ollama` `dc5b77e`: the page proof, and no generic early-consumer brief artifact is recorded.
443
+ - **Law.** `.agents/skills/orkestrel-harden/SKILL.md` § Run a real consumer.
444
+
445
+ ### Prove custody and the exact closure route before expensive use
446
+
447
+ When an expensive use depends on a freeze, a grade, progress, a replay, or next-request bytes, freeze one instrument lineage per gate, retain seals and original names, prove grade, progress, and replay through the entry used later, keep unsealed progress and raw spend while refusing unsupported grading and replay, capture after the result, validate seed custody, and compare all relevant next-request bytes separately, folded summary-first paths included.
448
+
449
+ - **Refuse.** A hash as proof of captured-byte execution or process isolation, because a hash proves provenance. A successful neighbor operation as proof of the intended route, because every custody operation has its own route and proof. A wrong-closure run read past its limit, because that run remains unsealed evidence only of the gauge. A failed read as a verdict, because a failed read yields no verdict.
450
+ - **Reading.** On a folded summary-first path: “the first chat is the summary request”. Alternate rubric routes and exact replay have separate receipts.
451
+ - **Example.** `@orkestrel/agent` `28486463`: the seed lineage freeze, and no single file or commit carries the merged custody protocol.
452
+
453
+ ### Separate developmental evidence, confirmation, and answer-path quality
454
+
455
+ When a study reports a measurement, hold the populations apart as the law states, fit preprocessing only on training data, measure accepted wrong, latent wrong, useful coverage, and the answers-only user's final decision, run helpful correction as a separate scenario, keep unknown, unselected, and unreached distinct, and replace a changed subject's assertions.
456
+
457
+ - **Refuse.** An old green result carried to a changed subject, because “none survives as a proof”. A labeling floor as a quality control, because that floor “cannot fail”. A label disagreement on equal products as a product difference, because that disagreement “is the labelers' own”. Semantic substitution from a lexical score, because its correlations did not earn that substitution. A population audit that asserts counts alone, because every count can hold while strata fail to cross, one value dominates, boundary values land together, or a ceiling under the bar makes the run measure the grid: in `@orkestrel/learn`, every count holds while all 200 ordinary messages are approvals and one pair of boundary values sits on 202 of 600 subjects.
458
+ - **Reading.** In the `@orkestrel/learn` package, on its study: “only the rubric contains population membership and expected outputs”. The answers-path scenario stays a specification, not a completed result, and no completed carrier is recorded.
459
+ - **Example.** `@orkestrel/learn` `a6a25c4`: the removal of the regression study held at historical commit `87a6463`, because the subject changes and its assertions no longer apply.
460
+ - **Law.** `.claude/rules/tests.md` § Expensive proofs.
461
+
462
+ ### Audit a consumer migration beyond compiling names
463
+
464
+ When a consumer migration compiles, census direct and indirect vocabulary, materialized fixtures, exhaustive switches, and defaulted branches, load the entry that resolves the disputed dependency, compare a clean published consumer, and keep recorded version strings unchanged where they describe evidence.
465
+
466
+ - **Refuse.** A typecheck as closure, because typechecking proves only the exhaustive portion. A name search as the census, because indirect fixtures stay outside it when “neither names `MessageInput`”. A check graph read as the whole consumer, because “the check excludes the provider entry”. A known-red nested NDJSON topology read as a published `@orkestrel/agent` defect, because that topology is not evidence of one and stays named until deduped plus a full study receipt.
467
+ - **Reading.** On a migrated consumer, the `ask` case reaches an old usage `else` branch.
468
+ - **Example.** `@orkestrel/mcp` `e1e7b11`: the clean-consumer fixture, whose exact filename the record omits.
469
+ - **Law.** `.claude/rules/tests.md` § Test contract.
470
+
471
+ ### Test author comprehension and observable meaning
472
+
473
+ When shorthand compiles to an existing execution engine, derive only entailed defaults and labels, compare semantic outcomes against full declarations, run the independent read the law names, keep full definitions for multi-factor and multi-line forms, and read the example as an author and count what it says twice before shrinking the example or moving the bar.
474
+
475
+ - **Refuse.** A line-count target met by guessing semantics or by checking one generated-key prefix, because `@orkestrel/learn` output exposes a `cap` key although its prefix test passes. A third form with no consumer, because a form needs a consumer. A `limit: null` member, because `AGENTS.md` § Design laws admits `null` only where an external format distinguishes it from omission.
476
+ - **Reading.** In the `@orkestrel/learn` package, on the `createRecipe` and `createRestriction` factories at commit `8d4ac62`, accepted at commit `2f95714`: six of six directions understood and 30 lines with imports. Both figures are this example's readings.
477
+ - **Example.** `@orkestrel/learn` `8d4ac62`: an independent reader receives only the recipe, and the record names no exact file for these factories.
478
+ - **Law.** The `orkestrel-harden` skill's Document one package reference § Write each surface.
479
+
480
+ ## Review
481
+
482
+ ### Enumerate breadth mechanically, then rule causes
483
+
484
+ When findings keep coming package by package, ask whether they are breadth or depth; for depth, reproduce the actual case and ask a design question when the class recurs; for a class that recurs across packages, run the census the law fixes before any reader marks a row, probe representation-aware pairs and their reachable public consequences, read the result as causes, prove each cause reachable through a public call before opening a row, repair the owning mechanism in one consumer, and spread the repair dependency-first.
485
+
486
+ - **Refuse.** A raw split count as separate fixes, because distinct splits reduce to fewer causes. A hand list as exhaustive coverage, because hand enumeration missed rows. A catch-to-empty traversal as coverage proof, because complete enumeration remains the requirement. A common instrument as each package's semantic oracle, because cross-package promotion and standing local assertions are complementary.
487
+ - **Reading.** On the census of the family of packages around `@orkestrel/contract` and `@orkestrel/reason`, `no commit recorded`: hand lists of 21 and 14 against 91 pairs, then all 279 marked from a script. No one commit owns the census method.
488
+ - **Example.** `@orkestrel/contract` and `@orkestrel/reason` `no commit recorded`: a ruling on causes before repair, where “Tightening runtime guards would have been wrong for most splits”.
489
+ - **Law.** `.agents/orchestration.md` § Depth, breadth, and machinery.
490
+
491
+ ### Bound depth by claims, release consequence, and an explicit stop
492
+
493
+ When a review round is about to open at a seam, set the release bar in the brief and the seam stop the law fixes before the round opens, repair or explicitly narrow a falsified named claim, let an outside finding block only above that package's bar, open a design question for a repeated class, and keep each deferred example with its trigger, moving a finding about what a word means to a known-limits list.
494
+
495
+ - **Refuse.** A brief that names no bar, because that brief makes every finding block. Tuning without end, or a promise silently abandoned, because a concrete deferred example and its trigger hold the promise on the record. Indefinite deferral on a trigger no permitted run can produce, because that trigger needs repair. Word-specific tuning before whole-model class evidence meets its reopening condition, because that tuning stays on the known-limits list until then. One package's bar carried to another, because the all-substantiated-findings bar of the `@orkestrel/contract` package differs from the fleet consequence bar and stays an explicit campaign ruling.
496
+ - **Reading.** In the `@orkestrel/interpret` package, on its number reader: “no further lane on the reader”, and a later audit closes the final repaired law at commit `74afa82`. No implementation commit is recorded for the stopping method.
497
+ - **Example.** `@orkestrel/interpret` `74afa82`: the final repaired law closes, while word-specific tuning stays on the `@orkestrel/learn` known-limits list.
498
+ - **Law.** `.agents/orchestration.md` § Size gate and § Depth, breadth, and machinery.
499
+
500
+ ### Reconcile evidence rather than reviewer votes
501
+
502
+ When a lane returns a finding or lanes disagree on a claim, reconcile by the procedure the law fixes on the built subject, extend a reproduced fixture where extending it is cheap, state what each lane examined, and keep the writer, gate, and acceptance roles distinct.
503
+
504
+ - **Refuse.** A sampled checker pass as runtime closure, because sampled parity remains unresolved. Agreement among lanes, on one engine or several, as closure, because no count of agreeing lanes replaces a reproduced input. A carried count as runtime closure, because that count reads “Carried, not verified by the checker or the fix pass”. A claim marked not run as a pass, because that claim holds no receipt.
505
+ - **Reading.** In the `@orkestrel/agent` package, on the falsify round at commit `bd681d39`: “An UNRESOLVED from an unread file beside a CONFIRMED with a receipt resolves to the receipt”.
506
+ - **Example.** `@orkestrel/agent` `069540aa`: the final repair closes on mutations, and its mutation closure has no later independent re-audit.
507
+ - **Law.** `.agents/skills/orkestrel-falsify/SKILL.md` § Reconcile and rule.
508
+
509
+ ### Test the proposed remedy against legitimate adjacent behavior
510
+
511
+ When a remedy is about to be prescribed or a design ruling is about to reach a unit, bound the remedy by what it would overcorrect as the law fixes, check the ruling against the code, probe the actual provider, codec, callback, or lifecycle, send a remedy that adds state or protocol to a design decision, and let a concrete counterexample overturn a prior design ruling.
512
+
513
+ - **Refuse.** Reasoning from a convenient name, because naming a reused capability is insufficient without matching semantics. Grouped asks or id caching with no wire inspection, because a request goes out per question and the internal `Message.id` field never reaches the wire. A measured reversal read as a need for a second acceptance owner, because evidence-based reversal alone does not prove that need.
514
+ - **Reading.** In the `@orkestrel/agent` package, `no commit recorded`, on the stored-role guard: tighter guards silently turn corrupt-present into absence, because the tightened guard returns undefined for corrupt data. Structural readability and stored admission stay different contracts.
515
+ - **Example.** `@orkestrel/agent` `e773887b` and `dd8dee79`: the actual refusal of the `createTimeout` factory settles the append ordering of a guarded run start.
516
+ - **Law.** The `orkestrel-falsify` skill's Reconciling a round and ruling on it reference § Bound the fix before briefing it.
517
+
518
+ ## Process
519
+
520
+ ### Rebase the effective brief before launching it
521
+
522
+ When a brief is about to launch after earlier units land or a scope stop changes what remains, re-read the cited tree and the expected command output, apply owner amendments, inventory indirect consumers, preflight every remaining path as the law fixes, give each row a stop clause naming what it must not add, such as a state or a second walk, and send a successor brief naming changed scope, known-red windows, ownership, and what prior receipts left unproven.
523
+
524
+ - **Refuse.** A fabricated future output that satisfies a checker, because “no output is created early”. A superseded release criterion, because the owner's amendment replaces that brief's version bump, migration table, and release commit. An unowned mechanism added after a premise falls, because a disproved premise stops the row. Orchestrator integration as writer acceptance, because the two stay distinct.
525
+ - **Reading.** On a rebased brief: “each cited line is re-read after the units ahead of it land”. No standalone method carrier is recorded.
526
+ - **Example.** `@orkestrel/agent` `no commit recorded`: the briefs over one shared setup.
527
+ - **Law.** `.agents/skills/orkestrel-dispatch/SKILL.md` § Write the brief and `.agents/orchestration.md` § Dispatch.
528
+
529
+ ### Own exact regions and hold the proof's entire input set
530
+
531
+ When a proof names files, shared regions, and inputs that can be built bytes or the live tree, assign ownership and holds as the law fixes, coordinate shared regions and one runner, distinguish immutable built bytes from suites reading the live tree, and inspect the actual index, diff, and status in the correct checkout before integrating.
532
+
533
+ - **Refuse.** A path list as isolation of foreign hunks, because a `git commit` command with a path takes the whole file. A staged patch that skips zero-context hunks, because skipped hunks “misplaced the staged lines”. A catch-all ownership line, because that line admits a test-imported guide, nested kind files, and unauthorized packages, which is a defect, not an exception. A shell recovery script, because shell recovery violates the TypeScript script law, so retain the recovery principle, not its implementation. A commit or a deletion justified by a past recovery, because that recovery implies no retrospective permission. Waiting on another lane's command while independent work remains, because the host bound counts commands, never a lane's whole life.
534
+ - **Reading.** On a proof that reads a built bundle: “The built bundle predates it” preserves that reading, and not later live-tree suite identity.
535
+ - **Example.** `@orkestrel/agent` `2c27a971`: the setup helper consolidation, beside a concurrent wave across `@orkestrel/study`, `@orkestrel/contract`, and `@orkestrel/ndjson`.
536
+ - **Law.** `.agents/orchestration.md` § Parallelism, `.agents/skills/orkestrel-dispatch/SKILL.md` § Write the brief, and `.agents/skills/orkestrel-parallel/SKILL.md` § Bound the host and § Run evidence commands.
537
+
538
+ ### Make service and data side effects explicit in the brief
539
+
540
+ When a command or a setup import can contact a service, a private store, or other data, name what it contacts as the law fixes, select dedicated service endpoints and separate hermetic projects, obtain runtime metadata through admitted public APIs, limit mirrors to required scratch inputs, and preflight expensive prerequisites.
541
+
542
+ - **Refuse.** Runtime metadata read from a private store, because admitted public APIs supply that metadata. A skipped green on a missing resource, because a missing resource is a stop or a red. A type mirror that copies unrelated private scratch, because a mirror holds required scratch inputs only. A resource cap read as a verdict, because a cap bounds work, not verdicts.
543
+ - **Reading.** On `@orkestrel/ollama` runtime metadata: the public `/api/tags`, `/api/show`, and `/api/version` endpoints supply that metadata, no barred data is inspected, and model and version facts are those recorded, not current discovery.
544
+ - **Example.** `@orkestrel/ollama` `6f8b522`: the live wave runs through the setup module of the `service` project.
545
+ - **Law.** `.agents/orchestration.md` § Permission floor and `.claude/rules/tests.md` § Live-service tests.
546
+
547
+ ### Distinguish source revision, packed bytes, registry resolution, and publication
548
+
549
+ When a proof depends on a source revision, packed bytes, a registry range, or a publication, build before a proof that packs with scripts disabled, choose the candidate after all packed-file changes, compare package contents when a records-only commit moves the `HEAD` revision, restore intended registry ranges, exercise the published dependency through a clean consumer, and report gates, prepublish stop, owner publication, and later adoption separately.
550
+
551
+ - **Refuse.** A records-only commit read as an exception to the re-pin law, because the law re-pins on every source move, so no one judges what counts as records-only. A release taken on a historical authorization, because a historical authorization grants a lane no release authority. A consultant dispatched on an unproved build, because a stale tarball wastes that run, so prove the build matches a commit by its source maps before dispatch.
552
+ - **Reading.** On a distribution proof: prepack rebuilding is “false for `test:distribution`, whose stage packs with `--ignore-scripts`”. Restored pins and local tarball tests do not prove registry availability, and no fresh registry receipt is recorded.
553
+ - **Example.** `@orkestrel/mcp` `e1e7b11`: the fixture needs no release, because its packed surface is unchanged.
554
+ - **Law.** The `orkestrel-publish` skill's reference Release laws § Fix a dependency before it publishes and § What a bump obliges, and its reference The release wave § Rule on the bump and § Prepare a layer.
555
+
556
+ ### Verify the actual runner and completion artifact
557
+
558
+ When a long run depends on a reporter, a runtime, arguments, setup imports, and the file that receives the exit line, probe the execution form before the run as the law fixes, down to reporter, thenable detection, command arguments, runtime binary, setup imports, and emitted exit artifact, use a stable tool location when an installation replaces the active tool, and keep receipts as the law fixes when only an unrelated input changes.
559
+
560
+ - **Refuse.** A watch on the wrong stream, because the launcher writes its exit line to the `.err` file, so a watch on the `.log` file misses that line. A wrapper assumed to spawn with no shell, because a wrapper cannot spawn without a shell, and JavaScript entries and argument arrays prove the route. A cause assigned to a lost process, because a missing process with unknown cause stays unknown. A polling or watch architecture or an arbitrary tool substitution, because neither follows from this method.
561
+ - **Reading.** On a Tinybench bench: Tinybench performs a construction invocation, which the `async: false` option fixes, and the minimal reporter omits sample output.
562
+ - **Example.** `@orkestrel/ollama` `6f8b522`: the chain runs the same `@orkestrel/scaffold` 0.0.122 from a stable `@orkestrel/agent` checkout, a historical deviation.
563
+ - **Law.** The `orkestrel-dispatch` skill's reference Long-running commands § Launch, and `.agents/orchestration.md` § Pace.
564
+
565
+ ### Promote a real shared mechanism and retire experiment residue
566
+
567
+ When a mechanism is used one time, repeated, or left behind after an experiment, reuse exact installed semantics first, keep a one-use wrapper in scratch, centralize reusable fixtures in allowed setup modules, promote a repeated procedure or a correctness-bearing mechanism as the law fixes, remove the option and orphaned machinery of a dropped experiment, and preserve the real consumer and update lifecycle wording when the owner reclassifies an option as product.
568
+
569
+ - **Refuse.** A test that pins an option as its real consumer, because “a capability needs a real consumer; a case that pins the key is none”. A browser Worker adopting a `NodeThread` job by name alone, because a passing WebWorker typecheck is not architectural permission. A proposed future API read as landed, because a proposed future API stays a proposal.
570
+ - **Reading.** In `@orkestrel/study` 0.0.9, `no commit recorded`: that release replaces the scratch progress reader. The promotion inventory is the artifact disposition record, not implemented promotions.
571
+ - **Example.** `@orkestrel/agent` `1a29fcf1`: the narrow and limit option cleanup.
572
+ - **Law.** `AGENTS.md` § Non-negotiable rules and § Design laws, `.agents/orchestration.md` § Depth, breadth, and machinery, and `.claude/rules/tests.md` § Shared test infrastructure.
573
+
574
+ ### Keep the requested product runnable while hardening its dependencies
575
+
576
+ When class-wide repairs proceed on the dependencies of a requested product, resolve what the product means before selecting an algorithm, put the deliverable first and let hardening run alongside, keep an executable milestone as the law fixes, reconcile changed scope against remaining work, and delete only under the owner's stated disposal decision.
577
+
578
+ - **Refuse.** A scalar cost regressor reinterpreted as a decision model, because the owner defines the model as the family's composition. Old assertions kept after the subject is replaced, because the regressor's assertions no longer apply. A campaign or a viewer deleted on an earlier decision, because no standing permission to delete follows from that particular decision. A historical artifact read as a live obligation, because a historical artifact stays evidence.
579
+ - **Reading.** In the `@orkestrel/learn` package, on its requested model: “the culmination of the reason package and all the packages that were built from it”. No generic scheduler of product and hardening work is recorded.
580
+ - **Example.** `@orkestrel/learn` `2f95714`: the accepted composed milestone, after commit `a6a25c4` removes the regressor and its app, with the recoverable parent `bcf4813`.
581
+ - **Law.** `.agents/orchestration.md` § Campaign and § Hold the plan.
582
+
583
+ ### Document the shipped behavior for a reader without campaign context
584
+
585
+ When shipped behavior is written for a reader who lacks the campaign, perform final prose after implementation and keep public names, TSDoc, and guide parity as the law fixes, execute behavioral examples, write upgrade effects against the prior served declarations, preserve historical fixture words, rename actual public consumers together, and keep grammatical exceptions.
586
+
587
+ - **Refuse.** A campaign id or stale planned behavior in a public explanation, because a stranger cannot read campaign and unit ids. A text pin as a runtime claim, because a text pin proves presence. A release note that drops a limitation for a more favorable old description, because release notes retain limitations. A rewrite of the recorded `@orkestrel/ollama` versions, because those versions stay untouched.
588
+ - **Reading.** In the `@orkestrel/agent` package, on its judgments: frozen-view migration and reactivated judgments are observable upgrade changes.
589
+ - **Example.** `@orkestrel/agent` `18a03b01`, `05f71b68`, and `942becd0`: naming commits that rename actual public consumers together.
590
+ - **Law.** `.claude/rules/documentation.md` § Parity and `AGENTS.md` § Work loop and § Design laws.
591
+
592
+ ### Let an evidence interface show only observations it actually owns
593
+
594
+ When an evidence interface shows a value that can be measured, predicted, replayed, incomplete, or illustrative, open an experiment page empty, label the value's actual state, preserve partial evidence with an incomplete state, permit prediction only from a completed fit, clear stale predictions when inputs change, verify actual compiled and resolved styles, handle a persisted `pagehide` event separately from permanent teardown, and generate export formats from one data representation.
595
+
596
+ - **Refuse.** A prediction from partial training, because “partial training never masquerades as a completed result”. A design mirror as style proof, because a mirror is not resolved styles. Synthetic curves or preloaded plausible benchmark values, because the page opens empty and those values are expressly refused. A confidence plot before calibration, because confidence plots wait for calibration. A PNG export from a second representation, because PNG is a rasterization of the same representation.
597
+ - **Reading.** In the `@orkestrel/learn` package at historical commit `87a6463`: “The page opens empty”. This reading is historical design and proposal evidence, not a browser re-proof or a shipped UI claim.
598
+ - **Example.** `@orkestrel/learn` `87a6463`: the historical `CostApplication`, `CostSession`, and `CostChart` classes, removed at commit `a6a25c4`, where class names alone do not establish exact files.
599
+
600
+ ## Refuse what failed
601
+
602
+ | Idea | Reading | Why it stays out |
603
+ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
604
+ | A plan hoist with no measured saving | In the `@orkestrel/agent` package, `no commit recorded`: a −27.9 ms reported gain with an interval crossing zero, reverted. | A cheap operation still needs its own shown saving before it earns a cache or hoist. |
605
+ | JSON serialization order as persisted identity | In the `@orkestrel/agent` package, hydrate succeeds but re-asks paid judgments. | Storage canonicalization must not silently erase value-equivalent memo hits. |
606
+ | An implicit allow on a tool call | In the `@orkestrel/agent` package, a deny callback reopens the window. | Authorization binds the object that will execute after all callbacks. |
607
+ | Agreement or a criterion fraction read as quality | Noninferiority cannot fail, and byte-identical products get differing labels. | Inspect the denominator and the behavior the instrument can distinguish. |
608
+ | A stale brief launched as written | The brief names the wrong owned files. | Rebase exact paths and rule placement against the destination state. |
609
+ | A version query or a hermetic-looking test presumed inert | A CLI version query contacts the daemon, and setup contacts the service at import. | Constrain actual command and setup side effects. |
610
+ | A prepack build assumed before packing | A pack with scripts ignored packs the old `dist` directory. | Prove built and packed identity separately from source history. |
611
+ | Every `HEAD` move read as a changed pack | A records-only commit changes no bytes. | Prove packed identity separately from source history, and leave the pin to the `orkestrel-publish` skill's Release laws reference. |
612
+ | An arm selected by its average alone | In the `@orkestrel/learn` package, the selection graph does not compare the leaders. | Interpret the written comparison and measured outcome, not a stronger surrogate. |
613
+ | Numeric examples as a treatment | In the `@orkestrel/learn` research, `no commit recorded`: multiplication examples multiplied plain numbers on 6/6 smoke rows. | Compare each shippable intervention on usefulness and every error channel. |
614
+
615
+ ## Settled arguments
616
+
617
+ - When a proposal caches every cheaper repeated operation, answer that a cache earns its lifetime and complexity only on its own measured term. Reopen only on that operation's own shown saving.
618
+ - When a proposal treats a missed target as a failed keep rule, answer that improvement targets, no-regression conditions, correctness merits, and owner exceptions are distinct dispositions.
619
+ - When a proposal quotes a figure from earlier in a campaign as the published baseline, answer that a campaign's earlier build is not the published artifact.
620
+ - When a proposal treats serialized order as judgment identity, answer that identity must survive the persistence transformation the public contract recommends.
621
+ - When a proposal calls a seed change pure noise, answer: inspect all identities the perturbation changes before interpreting variance.
622
+ - When a proposal offers a quality pass as proof that an optimization loses nothing, answer: measure the behavior the optimization can remove, not a convenient quality proxy.
623
+ - When a proposal gives an unreached gate another seed, answer that a reachable stratum on another arm answers a different question. Reopen only on a rewritten question.
624
+ - When a proposal reads scripted timing as proof of model usefulness or browser behavior, answer that a receipt covers the mechanism and host it drove.
625
+ - When a proposal adds another phrase-specific repair to a parser, answer that reader laws can generalize and vocabulary tuning needs whole-model evidence. Reopen only for a class of wrong decisions through the complete model.
626
+ - When a proposal calls a stricter check safer, answer that strictness names an owner, a representation, a stage, and a refusal direction.
627
+ - When a proposal makes an absent field approve, refer, or ask, answer that missing data is unread and only reached input faults become questions.
628
+ - When a proposal reduces approval wiring to an ID, answer: correlate the actual waiting call, not a visible name or loop event.
629
+ - When a proposal reads a failure as rollback or as no hang, answer: state the particular transaction and cancellation boundary rather than a universal.
630
+ - When a proposal lets structural validity admit a stored system role, answer that structural readability and stored admission are different contracts.
631
+ - When a proposal reads strict parsing as a finished response, answer that a syntactically valid stream still needs terminal settlement evidence.
632
+ - When a proposal adds recursive escaping across the whole renderer, answer: isolate the measured carrier first, then keep only what the renderer requires. Reopen only on a fixed-input measurement that establishes the carrier.
633
+ - When a proposal reads matching outputs as unchanged behavior, answer that read lifetime, effects, and ownership can change without a different final value.
634
+ - When a proposal offers a label pass or an equal outcome as a sufficient control, answer that the instrument must distinguish the loss it claims to exclude.
635
+ - When a proposal calls a repair pointless because a corpus count holds still, answer that coverage of input classes, not count movement alone, decides that proof.
636
+ - When a proposal carries a green historical study to a successor model, answer that receipts stay attached to their subject, source generation, and executed assertion.
637
+ - When a proposal reads a shorter factory or a similar API as suitable reuse, answer: derive only entailed semantics and test them through the real consumer.
638
+ - When a proposal lets an outside finding reopen everything, answer: repair the falsified claim and apply the stated package bar to unrelated findings. Reopen only on a finding that falsifies a named claim or crosses the declared release bar.
639
+ - When a proposal reads an absent source import as no legitimate consumer, answer that consumer existence and API creation need contract evidence, not a literal import count alone.
640
+ - When a proposal reruns every check after any change, answer: rerun the narrowest claim whose inputs changed and retain valid receipts.
641
+ - When a proposal holds a changed product direction to its old app and study obligations, answer: apply the owner's amendments before executing historical acceptance prose.
642
+ - When a proposal uses a semantic uncertainty signal to choose a replacement, answer that uncertainty can justify refusal without establishing another answer.