@orkestrel/scaffold 0.0.109 → 0.0.110

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 (51) hide show
  1. package/dist/agents/templates/brief.md +5 -1
  2. package/dist/bin/main.js +1 -1
  3. package/dist/bin/main.js.map +1 -1
  4. package/dist/host/agents/orchestration.md +45 -39
  5. package/dist/host/agents/platforms/windows.md +5 -0
  6. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +6 -6
  7. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -4
  9. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +1 -0
  11. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +18 -15
  12. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +27 -15
  13. package/dist/host/agents/skills/orkestrel-journey/SKILL.md +4 -0
  14. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +5 -5
  15. package/dist/host/agents/skills/orkestrel-parallel/references/cloud.md +28 -0
  16. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +13 -13
  17. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +3 -1
  18. package/dist/host/agents/skills/orkestrel-publish/references/window.md +1 -1
  19. package/dist/host/agents/templates/brief.md +5 -1
  20. package/dist/host/agents/transports/codex.md +1 -1
  21. package/dist/host/claude/AGENTS.md +1 -2
  22. package/dist/host/claude/agents/astra.md +2 -2
  23. package/dist/host/claude/agents/builder.md +3 -2
  24. package/dist/host/claude/agents/opus.md +2 -2
  25. package/dist/host/claude/agents/reviewer.md +2 -2
  26. package/dist/host/claude/agents/verifier.md +1 -1
  27. package/dist/host/claude/rules/campaign.md +1 -0
  28. package/dist/host/claude/rules/quality.md +3 -1
  29. package/dist/host/claude/rules/tests.md +11 -1
  30. package/dist/host/claude/rules/workspace.md +7 -8
  31. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  32. package/dist/host/codex/agents/astra.toml +8 -4
  33. package/dist/host/codex/agents/builder.toml +3 -3
  34. package/dist/host/codex/agents/opus.toml +4 -3
  35. package/dist/host/codex/agents/reviewer.toml +2 -2
  36. package/dist/host/codex/agents/verifier.toml +3 -3
  37. package/dist/host/codex/config.toml +1 -1
  38. package/dist/host/cursor/rules/orchestration.mdc +1 -1
  39. package/dist/host/dotfiles/oxlintrc.json +1 -1
  40. package/dist/host/guides/scaffold.md +5 -5
  41. package/dist/host/manifest.json +46 -40
  42. package/dist/host/tests/config.test.ts +7 -1
  43. package/dist/host/tests/policy.test.ts +38 -0
  44. package/dist/host/tests/setupPolicy.ts +361 -8
  45. package/dist/src/core/index.cjs +10 -6
  46. package/dist/src/core/index.cjs.map +1 -1
  47. package/dist/src/core/index.d.cts +5 -3
  48. package/dist/src/core/index.d.ts +5 -3
  49. package/dist/src/core/index.js +10 -6
  50. package/dist/src/core/index.js.map +1 -1
  51. package/package.json +1 -1
@@ -12,48 +12,50 @@ On a harness with no bridge, orchestrate natively, record the harness in the ros
12
12
 
13
13
  Name the harness family and its access route: Claude through Claude Code or the Claude CLI; Codex through Codex native agents or the Codex CLI; Cursor through the Cursor CLI, with Grok 4.7 Extra High for the Grok bench. Classify GPT-6 Astra, GPT-6.1 Sol, and GPT-6 Luna as Codex-family engines, including when another harness hosts the Orchestrator.
14
14
 
15
- | Engine | Job | Posture |
16
- | ----------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
- | Claude Fable 5.1 | orchestration in Claude Code: the plan, every decision, integration, acceptance | never dispatched: never a subagent, a bench, a fork, or a Workflow node, except as the consultant the user names for a wording and coherence pass after research and technical review |
18
- | Cursor Grok | context absorption, distillation, broad mapping, exploration | read-only; returns evidence, never decisions |
19
- | Claude Opus 5.5 | subjective design, design-fit review, implementation | proposes, audits, implements; never accepts its own work |
20
- | GPT-6 Astra | objective analysis, correctness audit, implementation | proposes, audits, implements; never accepts its own work |
21
- | Claude Sonnet 5.5 | bounded implementation of a closed shape, ecosystem reconciliation | executes a fully specified brief |
22
- | Claude Haiku 5.5 | bench drivers, small precise tasks, exact lookups, conformance, gates | executes a fully specified brief; edits no source |
23
- | GPT-6.1 Sol, GPT-6 Luna | mechanical units, drivers, small precise tasks, gates, exact lookups | executes a fully specified brief |
15
+ | Engine | Job | Posture |
16
+ | ----------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
+ | Claude Fable 5.1 | orchestration in Claude Code: the plan, every decision, integration, acceptance | never dispatched as a writer, a bench, a fork, or a Workflow node; dispatched only as a read-only consultant, for a bounded design question at the stop the Orchestrator set for a seam, or for the wording and coherence pass the user names |
18
+ | Cursor Grok | context absorption, distillation, broad mapping, exploration | as a bench: read-only; returns evidence, never decisions |
19
+ | Claude Opus 5.5 | subjective design, design-fit review, implementation | proposes, audits, implements; never accepts its own work |
20
+ | GPT-6 Astra | objective analysis, correctness audit, implementation | proposes, audits, implements; never accepts its own work |
21
+ | Claude Sonnet 5.5 | bounded implementation of a closed shape, ecosystem reconciliation | executes a fully specified brief |
22
+ | Claude Haiku 5.5 | bench drivers, small precise tasks, exact lookups, conformance, gates | executes a fully specified brief; edits no source |
23
+ | GPT-6.1 Sol | a fully specified unit with a closed shape | executes a fully specified brief |
24
+ | GPT-6 Luna | mechanical units, drivers, small precise tasks, gates, exact lookups | executes a fully specified brief |
24
25
 
25
26
  The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Claude Code, GPT-6 Astra in Codex, Cursor Grok in Cursor. The Orchestrator owns the plan, every decision, integration, and acceptance. When the harness is Codex or the Orchestrator uses a Codex-family engine, use the Codex column: map Opus to GPT-6 Astra, Sonnet to GPT-6.1 Sol, and Haiku to GPT-6 Luna; execute mapped Astra roles natively without an Opus bench probe. Under this mapping, assign review to another agent in a clean context and forbid self-review, including when writer and reviewer both use Astra. For other harnesses, review runs on an engine that did not write the work.
26
27
 
27
28
  ## Roles
28
29
 
29
- | Role | Job | Capability | Claude | Codex |
30
- | ------------ | ---------------------------------------------------------- | ------------ | ------------ | ----------- |
31
- | `grok` | absorption, distillation, broad mapping, exploration | reader | haiku driver | luna driver |
32
- | `analyst` | objective design argument or correctness audit on Astra | objective | haiku driver | astra |
33
- | `astra` | objective, constraint-heavy implementation on Astra | objective | haiku driver | astra |
34
- | `planner` | subjective design | subjective | opus | astra |
35
- | `reviewer` | design-fit or correctness review | subjective | opus | astra |
36
- | `opus` | subjective implementation (API shape, naming, guide voice) | subjective | opus | astra |
37
- | `builder` | one bounded unit with a closed shape, app layer included | closed-shape | sonnet | sol |
38
- | `checker` | mechanical conformance against criteria and rules | mechanical | haiku | luna |
39
- | `verifier` | gates and evidence commands, exit-code truth | mechanical | haiku | luna |
40
- | `scout` | exact bounded lookup of files, symbols, seams | mechanical | haiku | luna |
41
- | `distiller` | bulk reading when the Cursor bench is dark | reader | haiku | luna |
42
- | `researcher` | primary-source research when the Cursor bench is dark | reader | haiku | luna |
43
- | `orkestrel` | ecosystem reconciliation over supplied evidence | closed-shape | sonnet | sol |
44
-
45
- - Name the role and its engine in every dispatch. Reach a role by its own name.
30
+ | Role | Job | Capability | Claude | Codex |
31
+ | ------------ | -------------------------------------------------------------- | ------------ | ------------ | ----------- |
32
+ | `grok` | absorption, distillation, broad mapping, exploration | reader | haiku driver | luna driver |
33
+ | `analyst` | objective design argument or correctness audit on Astra | objective | haiku driver | astra |
34
+ | `astra` | objective, constraint-heavy implementation on Astra | objective | haiku driver | astra |
35
+ | `planner` | subjective design | subjective | opus | astra |
36
+ | `reviewer` | design-fit or correctness review | subjective | opus | astra |
37
+ | `opus` | subjective implementation (API shape, naming, guide voice) | subjective | opus | astra |
38
+ | `builder` | a fully specified unit with a closed shape, app layer included | closed-shape | sonnet | sol |
39
+ | `checker` | mechanical conformance against criteria and rules | mechanical | haiku | luna |
40
+ | `verifier` | gates and evidence commands, exit-code truth | mechanical | haiku | luna |
41
+ | `scout` | exact bounded lookup of files, symbols, seams | mechanical | haiku | luna |
42
+ | `distiller` | bulk reading when the Cursor bench is dark | reader | haiku | luna |
43
+ | `researcher` | primary-source research when the Cursor bench is dark | reader | haiku | luna |
44
+ | `orkestrel` | ecosystem reconciliation over supplied evidence | reader | sonnet | sol |
45
+
46
+ - Name the role and its engine in every dispatch. Reach a role by its own name. When a hosting harness offers both columns, the dispatch names the column each lane runs on.
47
+ - The capability column names the lane a role holds by default and the one a dispatch may assign (`reviewer`: subjective by default, objective when assigned; `orkestrel`: reader).
46
48
  - On a harness with no column, map each capability to an engine in the roster and route by that map; add the harness's column here when it carries campaign work.
47
49
  - A driver launches another harness's CLI and returns the journal path and session id with the result. It never judges or implements. Refuse a bench result that carries no journal path and session id; it ran on the driver.
48
50
  - `.agents/transports/<harness>.md` owns each bench's invocation, sandbox, journal, and recovery. `.claude/agents/` and `.codex/agents/` hold one file per role.
49
51
 
50
52
  ## Routing
51
53
 
52
- - Route by judgment load. Objective, constraint-heavy, mechanical-precision work goes to `astra`. API shape, naming, and documentation voice go to `opus`. A bounded unit whose brief or types fix its names, API, and architecture goes to `builder`, whatever its private lines; a unit that spans packages or leaves one of those open goes to `astra` or `opus`.
54
+ - Route by judgment load. Objective, constraint-heavy, mechanical-precision work goes to `astra`. API shape, naming, and documentation voice go to `opus`. A bounded unit whose brief or types fix its names, API, and architecture goes to `builder`; a unit that spans packages or leaves one of those open goes to `astra` or `opus`. Route a unit that creates or changes a cross-process or filesystem protocol (a lock, a marker, an atomic publish, termination handling, or a retry class) to `astra` or `opus`; a unit that leaves its mechanism open is not closed-shape, however closed its public shape looks.
53
55
  - Route all context absorption, distillation, broad mapping, and exploratory or fishing reads to `grok` on Cursor Grok 4.7 Extra High: terrain, prior art, diff sweeps, scattered sources. Keep decision-bearing reading with the decision owner. Fall back to `distiller` or `researcher` only when the Cursor bench is dark, and record the fallback; ease or cost never authorizes a fallback.
54
56
  - Keep small tedious precise tasks native: Claude Haiku in Claude, Codex Luna in Codex. Use `scout` for an exact bounded lookup; keep bench drivers, `checker`, and `verifier` on their mapped native engines. A bounded file scope does not turn context absorption or exploratory reading into a native lookup.
55
57
  - Route a unit that authors path-containment, import-resolution-boundary, unescaped-input, or credential-exposure proofs to `opus` from the start where `opus` runs on Claude, and record the Codex bench dark for that unit only. Under native Codex roles, report a harness refusal through § Deviation protocol.
56
- - Route gates to `verifier`. A writer's self-reported gate is not evidence.
58
+ - Route gates to `verifier`. A writer's self-reported gate is not evidence. A writer never holds the runner lane for its own acceptance; a gate a writer runs is an observation, never acceptance.
57
59
  - Under the Codex mapping, put falsify lanes on Astra or Sol at high effort; keep Luna for gates and verifier runs, never for a lane that must resolve runtime claims.
58
60
  - Work directly on a one-file change or a one-line fix, subject to the preceding routing rules. Route standalone lookups through `scout`. Dispatch when isolation, parallelism, a second engine, or a large read pays for the brief.
59
61
 
@@ -64,8 +66,8 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
64
66
  - Record the session identity separately from its task, turn, process, and message address. Record each session's harness, provider, model, options, workspace, responsibility, owned paths, continuation address, most recent task, and evidence paths in the roster, and preserve its prior task results. The roster is `coord/roster.md` of the live `orkestrel-parallel` round, or `tmp/units/roster.md` when no round is live.
65
67
  - Treat a live writer as an agent with an active assignment and edit authority. A retained session without an assignment holds no resource merely by existing. Preserve an explicit hold until its owner releases it.
66
68
  - Continue a unit through compaction. Before a handoff or context limit, record decisions, changed instructions, source identity, unresolved questions, failed and passing evidence, active process identities, ownership, and the next action. Compaction neither completes a task nor releases its files or processes.
67
- - On continuation, the Orchestrator sends the next bounded objective and the facts changed after the last turn. The continued agent reads changed or missing authority and the source regions that objective needs, and rechecks mutable facts such as source state and process liveness. Do not repeat unchanged bulk reads merely because a unit resumes.
68
- - Consult a suitable peer when a consequential approach remains open, evidence conflicts, or repeated attempts stop narrowing a failure. Give the peer the question, relevant evidence, attempted approaches, constraints, and requested answer. Use an existing specialist when its context helps and a fresh peer when the question needs an independent challenge.
69
+ - On continuation, the Orchestrator sends the next bounded objective and the facts changed after the last turn. The continued agent reads changed or missing authority and the source regions that objective needs, and rechecks mutable facts such as source state and process liveness. Do not repeat unchanged bulk reads merely because a unit resumes. A continuation that changes scope or acceptance, or authorizes a fix, is written first as `<unit>-brief-<n>.md` and sent as a pointer to that file; a message alone continues only an unchanged objective.
70
+ - Consult a suitable peer at the stop set for a seam, or earlier when a consequential approach remains open, evidence conflicts, or attempts stop narrowing a failure, without waiting for the user, and record the question, recommendation, evidence, and next check in the plan. Give the peer the question, relevant evidence, attempted approaches, constraints, and requested answer. Use an existing specialist when its context helps and a fresh peer when the question needs an independent challenge.
69
71
  - Keep consultation read-only and bounded. Ask for a recommendation, its evidence, uncertainty, and a concrete next check. The executor retains the work; the Orchestrator rules on scope and acceptance. Advice grants no authority and does not satisfy an independent review gate.
70
72
  - Resolve conflicting advice against the contract and observable evidence. Do not add consultation to routine steps or repeat it without a changed question or evidence.
71
73
  - When a requested launch channel fails, record the failure and whether a child was created. Before retrying an uncertain launch, inspect the recorded task or session. Use a permitted fallback with its actual model and options disclosed; retry a refused route only after a relevant condition changes.
@@ -85,7 +87,7 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
85
87
 
86
88
  ## Hold the plan
87
89
 
88
- - Open with the goal and acceptance criteria per `AGENTS.md` § Work loop, then estimate the scope: the units, the review and evidence each needs, and what stays out. When the estimate is large, agree with the user the estimate, the spend ceiling, and the stop line: how much lane time the work can take, and the point at which work stops and reports.
90
+ - Open with the goal and acceptance criteria per `AGENTS.md` § Work loop, then estimate the scope: the units, the review and evidence each needs, and what stays out. When the estimate is large, agree with the user the estimate, the spend ceiling, and the stop line: how much lane time the work can take, and the point at which work stops and reports. Derive an estimate or a process cap from a measurement of the same command, execution shape, and toolchain, and state that measurement beside the figure, or state that none exists.
89
91
  - Before each unit, name the plan step it serves. Cut a unit no step needs; set an unplanned idea aside in the plan and return to the step.
90
92
  - Add a tracked file only where the request, the plan, or a rule names it.
91
93
  - After every unit return, unexpected result, or user message, compare the work with the plan: mark what is done, restate the next step, and set aside what no longer serves the goal.
@@ -116,10 +118,13 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
116
118
  | medium | one opinion (`planner` or `analyst`) only when the shape is open | `opus`, `astra`, or `builder` by judgment load | one pass by an independent reviewer per § Engines, on numbered claims about the contract and the risky seams | `verifier` on the touched projects |
117
119
  | large | one independent round: `planner` and `analyst`, same brief, clean contexts, blind to each other | disjoint units in parallel | one `orkestrel-falsify` round on the integrated result | `verifier` tree-wide, once |
118
120
 
119
- - Never run a review on a small change. Never run a second design round on the same brief.
121
+ - Never run a review on a small change. Never run a second design round on the same brief. A design question a repair round opens is its own brief, not a second design round on the campaign's brief.
120
122
  - A review judges types, tests, and implementation. It reports comment, TSDoc, or guide wording only where the text contradicts the final behavior, and no fix round opens for prose alone.
121
- - A fix round re-audits the repaired claim only. A fix that adopted the reviewer's prescription verbatim closes with a mutation probe (disable the load-bearing line, watch the test fail, restore it); `node .agents/skills/orkestrel-falsify/scripts/mutate.ts --edits EDITS.md -- COMMAND` runs the probe and proves the restore. A fix that departs from it gets one pass by an independent reviewer per § Engines.
122
- - When review rounds at one seam keep surfacing defects without converging on their source, follow `.agents/skills/orkestrel-falsify/SKILL.md` § End the depth search.
123
+ - Before a repair is dispatched, class its remedy as a correction, a design question, or a deferral; a remedy that adds a mechanism (a file operation, a state, a protocol step, or a retry class) is a design question that goes to one `planner` or `analyst` pass carrying measured platform facts.
124
+ - A fix round re-audits the repaired claim only. A fix that departs from the reviewer's prescription gets one pass by an independent reviewer per § Engines.
125
+ - Every repair, a prescription adopted verbatim included, closes with a mutation probe on its load-bearing line (disable it, watch the test fail, restore it); `node .agents/skills/orkestrel-falsify/scripts/mutate.ts --edits EDITS.md -- COMMAND` runs the probe and proves the restore. Where the repair adds or changes a process proof, the proof's repeat run under suite load closes it too.
126
+ - Before another round at the same seam, weigh whether a further repair beats a design question, set and state in the brief the stop for that seam and its reason, re-examine it at every round, and end the depth search with a design question when a round introduces as many defects as it closes, a repair adds a mechanism, findings stop converging, or the cost outgrows the goal's importance. `.agents/skills/orkestrel-falsify/SKILL.md` § End the depth search owns how the search ends.
127
+ - A repair round at a seam carries only rows whose remedy serves that seam; a finding outside it waits for the next round or the deferral list.
123
128
  - An all-confirmed round ends the audit. A round needs an added or repaired claim to test; reviewer appetite is not a subject.
124
129
 
125
130
  ## Campaign
@@ -140,11 +145,11 @@ A large change opens with a concise goal and its exit criterion, short enough to
140
145
  - Parallelize independently owned work when useful progress can overlap. Reuse suitable sessions per § Sessions and consultation, bound each objective, and count coordination and verification costs when choosing the lanes. § Cache governs model and tool settings.
141
146
  - Judgment stays narrow: a design or review pass is at most the two lanes the size gate names, each in a clean context, blind to the other, and it runs once. Never fan judgment out further, and never run it as a loop.
142
147
  - Keep every lane, in this session and in peer sessions on the same machine, within the host budget of `.agents/skills/orkestrel-parallel/SKILL.md` § Bound the host.
143
- - One writer per checkout, except under `orkestrel-parallel`: there, at most three writers share one checkout, each owns disjoint files and disjoint regions of shared files, and one runner lane owns every test, check, and build process. Otherwise give parallel writers disjoint owned files, and give a writer its own worktree under `tmp/worktrees/` only when two units must write the same files at once. Commit a checkpoint before a writing dispatch.
148
+ - One writer per checkout, except under `orkestrel-parallel`: there, as many writers share one checkout as the host budget and disjoint ownership allow, each owning disjoint files and regions, and one runner lane owns every test, build, and tree-wide gate; `.agents/skills/orkestrel-parallel/SKILL.md` § Implement in phases names the checks a writer runs on its owned files. Otherwise give parallel writers disjoint owned files, and give a writer its own worktree under `tmp/worktrees/` only when two units must write the same files at once. Commit a checkpoint before a writing dispatch.
144
149
  - Fold every branch, clone, copy, or worktree an agent creates back into the original checkout's main branch with its changes left uncommitted there, so the user sees the whole difference from that branch. Commit inside the branch, clone, copy, or worktree as its unit needs, then remove it and delete its branch.
145
150
  - In a checkout another session shares, read the branch and `git status` before a write, and stop and ask the user when another session's uncommitted work is present.
146
151
  - Shared files are report-only; a unit returns an exact patch as an edit file that `.agents/skills/orkestrel-dispatch/scripts/patch.ts` applies. Under `orkestrel-parallel`, a writer edits its owned regions of a shared file directly.
147
- - Scope validation by the claim and its input dependencies, not by writer ownership alone. Under `orkestrel-parallel`, the runner owns checks and obtains the required write holds; § Pace rules on reruns. Never run tree-wide `format`, lint `--fix`, or `build` beside a live writer.
152
+ - Scope validation by the claim and its input dependencies, not by writer ownership alone. Under `orkestrel-parallel`, the runner owns every test, build, and tree-wide gate (§ Implement in phases names a writer's owned-file checks) and obtains the required write holds; § Pace rules on reruns. Never run tree-wide `format`, lint `--fix`, or `build` beside a live writer.
148
153
  - One Grok lane at a time; queue the rest. An empty lane beside a live probe is starvation, not darkness.
149
154
  - The Orchestrator's own sweep is a writing dispatch: run it before or after the units, never beside them.
150
155
 
@@ -206,11 +211,11 @@ The Orchestrator triages: obvious correction → tighten and re-dispatch; missin
206
211
 
207
212
  ## Cleanup
208
213
 
209
- - When a unit is accepted, carry its measurements, unresolved findings, and any instrument worth keeping into the commit message, a tracked design, or a test, then delete its `tmp/units/<unit>-*` files and its bench journals.
214
+ - When a unit is accepted, carry its measurements, unresolved findings, and any instrument worth keeping into the commit message, a tracked design, or a test, then delete its `tmp/units/<unit>-*` files and its bench journals. Before a unit's files go, carry its effective brief (objective, corrections, source identity, rulings) into the tracked plan or the acceptance commit. Delete or move no path a live lane's brief names.
210
215
  - `.claude/rules/campaign.md` owns what `.orkestrel/` holds and when each file goes; git history is the archive.
211
216
  - Delete a probe from the source tree before the unit returns; promote a probe that settled a claim into a test.
212
217
  - Run `node .agents/skills/orkestrel-dispatch/scripts/sweep.ts --report` at acceptance; it lists leftovers under `tmp/` and `.orkestrel/` by age and deletes nothing. Run the same script with `--tmp` after the last live unit exits; it deletes files older than its threshold and refuses while a journal is changing.
213
- - A campaign artifact never lives in the package it is about.
218
+ - A campaign artifact lives under `.orkestrel/<package>/`, never under the package's source, test, or distribution tree.
214
219
 
215
220
  ## Cache
216
221
 
@@ -222,9 +227,10 @@ The Orchestrator triages: obvious correction → tighten and re-dispatch; missin
222
227
  ## Acceptance
223
228
 
224
229
  - No writer's and no bench's self-assessment is authoritative. The Orchestrator accepts after the review and the gates the size gate names.
230
+ - An accepted claim or gate row names the independent receipt (command, input identity, exit) that closed it; a writer's report states implementation status and never closure.
225
231
  - Accept when the exit criterion is met and the gates are green. Reopening an accepted criterion is the user's instruction, not a reviewer's finding.
226
232
  - Before calling work ready, try the shipped result as the user will, on the build they run, and report what did not run.
227
233
  - Substitute an engine only when the same session recorded the bench dark; name the fallback in the brief and the carrying commit.
228
234
  - In a repository whose package the registry already serves, commit on the main branch and push it only on the user's go-ahead.
229
- - Commit by explicit paths. Before a push, read `git log @{upstream}..` and push only commits meant to publish together; hold a push while a commit depends on an unpublished local pin.
235
+ - Commit by explicit paths. Before a push, read `git log @{upstream}..` and push only commits meant to publish together; hold a push while a commit depends on an unpublished local pin. Push a commit only after the gate run on that commit, or record the push as ungated.
230
236
  - Publishing is the user's decision and credential; `orkestrel-publish` owns the release procedure, the bump rules, and the dependency-tarball rules.
@@ -9,12 +9,16 @@ The commands an agent runs on a Windows host, and their quirks. `.claude/rules/p
9
9
  - Kill a recorded tree with `taskkill /pid <pid> /T /F`. `launch.ts` kills the tree at its cap on this host.
10
10
  - Detach a run from the session's process tree with WMI: `Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = '<command>' }`. The run starts under `WmiPrvSE.exe`, outside the session's job and process tree (verified 2026-10-16). It receives the user's registry environment, not the caller's, so pass each value it needs on its command line. Record its journal and pid-file paths before the launch.
11
11
  - Spawn npm without a shell through its JavaScript entry: `node <node directory>/node_modules/npm/bin/npm-cli.js <arguments>`. A `.cmd` shim cannot start without a shell, and `launch.ts` reports exit `127`.
12
+ - `cmd /c` keeps a trailing space inside `set VAR=value && …`; write `set "VAR=value"`.
13
+ - Deliver a console Ctrl+C through `WScript.Shell` `AppActivate` then `SendKeys('^c')` after confirming activation when no computer-use tool is available.
14
+ - A `rename` onto a freshly hard-linked file can return `EPERM` while a scanner holds it.
12
15
  - A child CLI can leak orphaned `conhost.exe` processes and open console windows. Count them with `Get-Process conhost` at each launch while such a lane is live.
13
16
 
14
17
  ## PowerShell 5.1
15
18
 
16
19
  - Chain with `;` and gate with `if ($?) { ... }`; `&&` and `||` are parse errors.
17
20
  - Edit text with the harness's file tools, never `Get-Content` piped through `-replace` into `Set-Content`. `-replace` matches case-insensitively, `Set-Content` writes the ANSI code page, `Set-Content -Encoding utf8` and `Out-File` write a byte-order mark, and the round trip turns non-ASCII punctuation into mojibake.
21
+ - Write a JSON file a tool must parse to a new path through the file tool or `[IO.File]::WriteAllText` with a BOM-free `UTF8Encoding`.
18
22
  - Write a commit message to a file with the harness's file tool and commit with `git commit -F <file>`. A here-string carrying double quotes splits into stray arguments, and a byte-order mark in the file lands in the commit subject.
19
23
  - Never pipe a command whose exit code gates the next step, a `node` probe included, into `Select-Object -First` or `-Last`. The cut pipeline kills the command early and leaves a misleading `$LASTEXITCODE`. Run it bare, read `$LASTEXITCODE`, or decide from `git status --porcelain` and `git rev-parse`.
20
24
  - PowerShell drops a bare `--` before a native command, so `npm run <script> -- <arguments>` loses the separator. Run the tool's own entry with an argument array, or call `npm.cmd`.
@@ -34,4 +38,5 @@ The commands an agent runs on a Windows host, and their quirks. `.claude/rules/p
34
38
  ## Deleting untracked files
35
39
 
36
40
  - When a sweep you run by hand deletes untracked files, send them to the Recycle Bin through a shell file operation with undo, never permanent deletion, and report what went there. Leave emptying the bin to the user; hand them `Clear-RecycleBin -Force`.
41
+ - `DeleteDirectory(..., SendToRecycleBin)` fails on an npm-installed tree; recycle each file with `DeleteFile` and remove the emptied folders.
37
42
  - Remove a worktree with `git worktree remove`. Delete a leftover `node_modules` junction without recursing into its target.
@@ -25,11 +25,11 @@ description: >-
25
25
  ## Write the brief
26
26
 
27
27
  1. A small native unit's brief is the dispatch message: scope, law references, expected result. Otherwise run `node .agents/skills/orkestrel-dispatch/scripts/brief.ts --unit <unit> --lane <lane>` and fill every section; write `none` in an empty one. A re-run takes the `-<n>` file the script writes; never edit a launched brief.
28
- 2. Back every fact the unit will act on with the command and output that established it. Check a fact against the tree, not against another artifact.
29
- 3. Scope by what the change makes false: run the `orkestrel-scout` skill's `map.ts --refs` and `--census` for an existing member of any enumerated population the unit extends, and own every file that comes back, with the tests that pin the behavior, the fixtures derived from a constant, and the materialized copy of a template.
30
- 4. Order acceptance criteria cheap-first (regenerate, typecheck, lint, scoped test). Name a timing-sensitive or tree-wide gate as an observation, not a criterion.
28
+ 2. Back every fact the unit will act on with the command and output that established it. Check a fact against the tree, not against another artifact. A cross-process or filesystem brief carries a platform-facts table (operation, host, measured code, and the probe that measured it) and marks each unmeasured assumption. An investigation brief names the failing command and state, the candidate layers, the readings that distinguish them, the test that pins the existing behavior, the fix pre-approved for each confirmed reading, and the stop for every other outcome. A failure that passes alone but repeats in the sequence that produced it is an order-dependent defect to diagnose, never a timing miss to record, and an unchanged rerun of that sequence adds no evidence. A brief built on an earlier lane's evidence names what that evidence left unproven and schedules the cheapest run that covers the remainder before any long run. A brief carries the failure output it asks the unit to repair inline or under the unit's own checkout, never only as a path the unit may not reach.
29
+ 3. Scope by what the change makes false: run the `orkestrel-scout` skill's `map.ts --refs` and `--census` for an existing member of any enumerated population the unit extends, and own every file that comes back, with the tests that pin the behavior, the fixtures derived from a constant, and the materialized copy of a template. A brief that prescribes a mechanism step by step lists the inherited operations that keep their behavior, so its stop line guards only what the prescription changes.
30
+ 4. Order acceptance criteria cheap-first (regenerate, typecheck, lint, scoped test). Name a timing-sensitive or tree-wide gate as an observation, not a criterion. Place a run whose cost outweighs the discrimination it adds after the cheap checks and after the inputs stabilize. Before a brief ships, run every acceptance check it states as a command's expected output against the destination tree and word the row from that reading.
31
31
  5. State that the executor performs the work itself and spawns nothing. A bridge driver carries the brief unaltered and returns the journal path and session id.
32
- 6. Name the host conditions the unit will hit: shell, sandbox, network, files expected dirty, commands known to fail. Give absolute paths for work outside the session's root; a lane's shell can restart in another directory between calls.
32
+ 6. Name the host conditions the unit will hit: shell, sandbox, network, files expected dirty, commands known to fail. Give absolute paths for work outside the session's root; a lane's shell can restart in another directory between calls. A brief that folds prepared work onto a checkout inventories the tracked, staged, and untracked inputs, checks the chosen patch method against the destination's actual state, and names the conflict precedence and a bounded recovery.
33
33
  7. Fill each placeholder at its value sites only; a global replace also rewrites a stop clause that names the placeholder.
34
34
  8. Run `brief.ts --check <brief>` and fix every missing path before the launch.
35
35
 
@@ -59,9 +59,9 @@ An external engine widens capacity and inherits no authority; treat its output a
59
59
 
60
60
  ## Accept
61
61
 
62
- 1. Capture a native report to `tmp/units/<unit>-report.md`, or read a bench answer with `result.ts --<bench> <journal> --out <path>`.
62
+ 1. Capture a native report to `tmp/units/<unit>-report.md`, or read a bench answer with `result.ts --<bench> <journal> --out <path>`. A brief states the unit's estimated cost and the cost at which it stops and reports, and the unit's report records the observed cost beside that estimate.
63
63
  2. Run `cite.ts <report>` and discard every claim whose citation does not resolve before reading the rest.
64
- 3. Verify with direct evidence: `git status --porcelain`, the diff, and the scoped validation the brief named. A writer's self-report is not evidence.
64
+ 3. Verify with direct evidence: `git status --porcelain`, the diff, and the scoped validation the brief named. A writer's self-report is not evidence. A receipt counts for every claim its input coverage proves, whatever command produced it; a passing part of an aborted run is not a receipt.
65
65
  4. Run the review the size gate names, then integrate: apply shared-file patches serially, each an edit file in the shape `patch.ts` reads, with `patch.ts EDITS.md --plan`, then `--apply`; route an added type, mechanism, or criterion to a successor unit.
66
66
  5. Write the acceptance commit message with what changed and what the unit measured; record `durationMs` when it informs a cap or a performance claim.
67
67
  6. Run `sweep.ts --unit <unit> --delete` to remove the unit's brief, report, claims, journal, errors, status, pid, and last-message files. Delete any probe the unit left in the tree. In a campaign, update `.orkestrel/<package>/plan.md` and the ledger, and delete a closed seam's verdict. `.agents/orchestration.md` § Cleanup owns the `--report` and `--tmp` runs.
@@ -29,7 +29,7 @@ Apply these rules to every command that outlives the turn that starts it: a benc
29
29
  - Read liveness, list descendants, and kill with the commands of `.agents/platforms/<platform>.md`: list every descendant of the recorded pid, print the list, then kill each listed id and the recorded pid.
30
30
  - Refuse a list holding PID 1, the harness shell, or an id outside the descent of the recorded pid. At the cap, `launch.ts` kills what the platform page states; kill the remaining listed descendants by hand.
31
31
  - Confirm the recorded process and every listed descendant are gone before another writer takes the files. Check owned-file mtimes before dispatching the substitute.
32
- - Re-run a timing failure alone, after the unit exits, before believing it; a unit's own re-run is never alone.
32
+ - Rerun a failure alone only after the unit exits, as a reading and never a verdict, per `.agents/skills/orkestrel-dispatch/SKILL.md` § Write the brief; a unit's own rerun is never alone.
33
33
 
34
34
  ## Cap
35
35
 
@@ -42,12 +42,12 @@ Write `tmp/units/<unit>-claims.md` and point every lane at it. Read `references/
42
42
 
43
43
  Every lane returns exactly this:
44
44
 
45
- 1. Numbered verdicts in claim order, one value each: `CONFIRMED` (held against a falsification attempt, with the attempt), `BROKEN` (the failing input, state, or interleaving plus the smallest correct fix), `UNRESOLVED` (what would settle it; a claim whose only evidence is the writer's report), `NOT-EVIDENCED` (the capture that is missing).
45
+ 1. Numbered verdicts in claim order, one value each: `CONFIRMED` (held against a falsification attempt, with the attempt), `BROKEN` (the failing input, state, or interleaving), `UNRESOLVED` (what would settle it; a claim whose only evidence is the writer's report), `NOT-EVIDENCED` (the capture that is missing). `BROKEN` carries the smallest correct fix only where that fix adds no mechanism; otherwise it carries the violated property and the design question it opens.
46
46
  2. Findings outside the claims, each substantiated to the `BROKEN` standard. After them, list each cost finding that `.claude/rules/quality.md` § Performance rules advisory, marked `ADVISORY`; an advisory never enters the terminal line.
47
47
  3. Tested and held: tests no verdict line carries, and the adjacent behavior that looks like the defect and is correct.
48
- 4. One terminal line: `VERDICT: PASS` or `VERDICT: FAIL <claim numbers>; outside the claims: <finding ids or none>`. `PASS` needs every claim `CONFIRMED` and no substantiated outside finding.
48
+ 4. One terminal line: `VERDICT: PASS` or `VERDICT: FAIL <claim numbers>; outside the claims: <finding ids or none>`. `PASS` needs every claim `CONFIRMED` and no outside finding in the terminal line. An outside finding enters the terminal line only above the bar the brief names, and no severity word moves a finding across that bar; a brief that names no bar puts every substantiated outside finding in the terminal line.
49
49
 
50
- Before confirming a claim about a proof, the lane names the mutation that would make the proof fail and states whether the assertions distinguish it. No process diary.
50
+ Before confirming a claim about a proof, the lane names the mutation that would make the proof fail and states whether the assertions distinguish it. A re-audit of a repair reports, beside its re-verdicts, every defect the repair introduced and every requirement it dropped. No process diary.
51
51
 
52
52
  ## Reconcile and rule
53
53
 
@@ -66,4 +66,4 @@ Write `.orkestrel/<package>/<unit>-audit-verdict.md` with the lanes that ran, th
66
66
 
67
67
  ## End the depth search
68
68
 
69
- When review rounds at one seam keep surfacing defects without converging on their source, name what the audit is for, dispatch one blind lens per station of the stream the defect moves along, locate the source, and plan from the source. A subject that reprices on every edit (a count, a census) is not a seam; drop the claim.
69
+ Enter the depth search at the stop § Size gate set for the seam or when its signals appear, and end it with a design decision, never a repair row. Name what the audit is for, dispatch one blind lens per station of the stream the defect moves along, locate the source, and plan from the source. A subject that reprices on every edit (a count, a census) is not a seam; drop the claim.
@@ -11,6 +11,7 @@ Give every claims brief these rows.
11
11
  - **Already established.** What the Orchestrator verified directly, so no lane re-derives it or re-reports it. State that the Orchestrator verified each item itself.
12
12
  - **Review evidence.** The actual diff and the actual `git status --porcelain` output, by path. For a rendered or externally driven surface, the capture; source is corroboration.
13
13
  - **Numbered falsifiable claims.** Written to `tmp/units/<unit>-claims.md`, one file both lanes read. Each claim names a property a concrete input, state, or interleaving could show false. Assign a primary lane where the lanes differ in strength; no lane skips a claim. The claim set is the round's scope: cover what the subject owns, then hold it closed. A finding against something no claim names enters the verdict only when substantiated to the `BROKEN` standard; otherwise it is a claim for the successor brief.
14
+ - **Release bar.** The observable consequences that make a finding outside the claims enter the terminal line, or `none`; a brief that names none puts every substantiated outside finding there. In a harden campaign, the plan's bar.
14
15
  - **Unknowns.** What the Orchestrator does not know that the round needs, and how the lane reports on it.
15
16
 
16
17
  ## The lane's brief
@@ -51,6 +51,7 @@ Record which engine was right and on what.
51
51
  ## Rule
52
52
 
53
53
  - Every retained finding names the fix-brief item that carries it; walk the list once.
54
+ - Class every retained finding's remedy per `.agents/orchestration.md` § Size gate before it enters a fix brief.
54
55
  - Drop, on the record, anything no lane can substantiate against the evidence.
55
56
  - Promote anything that must outlive the round into a durable artifact before the working files are swept.
56
57
  - Assign the fix round per `.agents/orchestration.md` § Size gate. The next round's brief is this round's successor.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: orkestrel-harden
3
- description: Research, audit, refactor, implement, centralize, test, document, and locally verify an individual Orkestrel TypeScript package to enterprise-grade production readiness under the repository's current AGENTS.md. Use when asked to fill missing or deferred capabilities, compare upstream or legacy implementations, salvage prior art, centralize source or test declarations, eliminate nested functions or superfluous wrappers, maximize declared @orkestrel dependencies—especially @orkestrel/contract—or add rigorous real-implementation and live-service tests. Select only the phases required by a narrow request; run the full workflow for production readiness or comprehensive hardening. A guide, README, or TSDoc pass on one package runs the document phase alone.
3
+ description: Research, audit, refactor, implement, centralize, test, document, and locally verify an individual Orkestrel TypeScript package to enterprise-grade production readiness of its own contract on its supported hosts under the repository's current AGENTS.md. Use when asked to fill missing or deferred capabilities, compare upstream or legacy implementations, salvage prior art, centralize source or test declarations, eliminate nested functions or superfluous wrappers, maximize declared @orkestrel dependencies—especially @orkestrel/contract—or add rigorous real-implementation and live-service tests. Select only the phases required by a narrow request; run the full workflow for production readiness or comprehensive hardening. A guide, README, or TSDoc pass on one package runs the document phase alone.
4
4
  ---
5
5
 
6
6
  # Harden an Orkestrel package
@@ -34,7 +34,7 @@ Load [contract.md](references/contract.md) whenever the package declares `@orkes
34
34
 
35
35
  Load [centralization.md](references/centralization.md) for every structural lane and as a mandatory cleanup pass after capability or hardening work.
36
36
 
37
- Load [hardening.md](references/hardening.md) for the hardening lane and for any request involving concurrency, lifecycle pressure, security boundaries, real services/models, test discovery, or package inspection.
37
+ Load [hardening.md](references/hardening.md) for the hardening lane, for any request involving concurrency, lifecycle pressure, security boundaries, real services/models, test discovery, or package inspection, and before any repair round at a seam.
38
38
 
39
39
  Load [document.md](references/document.md) for the documentation lane and for step 10 of every other lane.
40
40
 
@@ -44,30 +44,33 @@ Load [equivalence.md](references/equivalence.md) for a structural lane whose rew
44
44
 
45
45
  ## Execute the workflow
46
46
 
47
- 1. **Bound the campaign.** Record requested outcomes, in-scope environments/domains, explicit exclusions, supported hosts, dirty files, and evidence needed for acceptance.
47
+ 1. **Bound the campaign.** Record requested outcomes, in-scope environments and domains, explicit exclusions, supported hosts, dirty files, and the evidence acceptance needs. Draw the package's bounds: the contract its types and guide promise, the hosts it supports, and each host, runtime, or harness behavior it depends on but does not own, with what the contract promises when that behavior fails. Set the campaign's stops from the package's complexity and the goal's importance (the repair effort a seam receives before a design question, the pressure a proof applies, the cost a round may spend), state each stop with its reason in `.orkestrel/<package>/plan.md`, and re-examine every stop at each phase boundary. As soon as a candidate commit exists, run the package's release chain in a fresh clone on each reachable supported host, before any review round, as a baseline observation that `.agents/orchestration.md` § Campaign's Verify phase replaces, and rerun only the checks a later change invalidates.
48
48
  2. **Map before editing.** Trace public types, implementations, callers, tests, guides, exports, runtime boundaries, installed Orkestrel dependencies, and applicable legacy/upstream references.
49
- 3. **Establish the intended contract.** Build a capability/defect matrix. Separate verified fact from inference. Mark each row implement, repair, retain, or exclude with a reason. The matrix is fixed at this step and is the campaign's definition of done: every later step serves a row, and work that serves no row belongs to the next campaign. The row set is fixed; the planned work that closes it is not. Re-baseline that work at each phase boundary per `.agents/orchestration.md`, which owns the step and its boundary with rescoping.
50
- 4. **Design types first.** Update guide/spec intent and `*/types.ts` before implementation, under the root design laws. A contract that needs a compatibility shim is the wrong contract.
49
+ 3. **Establish the intended contract.** Build a capability/defect matrix inside the bounds step 1 drew, per [hardening.md](references/hardening.md) § Build the risk and seam matrix. Separate verified fact from inference. Mark each row implement, repair, retain, or exclude with a reason. Record the matrix in the tracked `.orkestrel/<package>/plan.md` as claims, a release bar, and a deferral list before the first writer: the claims are the campaign's definition of done; the bar names the observable consequences that make a finding outside the claims blocking; the deferral list (`.claude/rules/campaign.md` § Content) holds every other finding. The row set is fixed at this step: a finding a later step raises enters a row's repair or the deferral list, never the row set, and a row the user adds is a rescoping the ledger records. Re-baseline the planned work at each phase boundary per `.agents/orchestration.md`, which owns the step and its boundary with rescoping.
50
+ 4. **Design types first.** Update `*/types.ts` and record the design decision before implementation, under the root design laws; write guide prose at the root's final pass. A contract that needs a compatibility shim is the wrong contract.
51
51
  5. **Implement completely.** Finish every in-scope branch and reuse the exact installed Orkestrel primitives whose semantics match.
52
52
  6. **Prove each defect before repairing it** per the defect rule in `AGENTS.md` § Work loop. A repair with no red-then-green record is unproven.
53
53
  7. **Consolidate.** Run the complete centralization and wrapper sweep. Update all call sites to the real symbol rather than leaving aliases or 1:1 delegates.
54
- 8. **Challenge seams.** Add deterministic tests for invariants, boundaries, failures, lifecycle, cleanup, cancellation, concurrency, malformed or unexpected input, and resource pressure as applicable, under the test rules' real-implementation law.
54
+ 8. **Challenge seams within the bounds.** Add deterministic tests for invariants, boundaries, failures, lifecycle, cleanup, cancellation, concurrency, malformed or unexpected input, and resource pressure as applicable, under the test rules' real-implementation law and [hardening.md](references/hardening.md) § Challenge lifecycle and pressure. A seam is the package's contract meeting a boundary; prove a boundary the package does not own only as far as the contract promises about it, and treat a finding past that promise per [hardening.md](references/hardening.md) § Hold the package's bounds. Set each pressure proof per that section, which points at `.claude/rules/tests.md` § Expensive proofs for the repeat count and acceptance under suite load.
55
55
  9. **Use live services deliberately.** Put real external services/models in their dedicated project, require readiness, and make each request minimally sufficient, stable across the service's nondeterminism, and behaviorally meaningful. For a foreign-client claim, apply the seam row in [hardening.md](references/hardening.md) § Use real implementations.
56
56
  10. **Document the final behavior** per [document.md](references/document.md).
57
- 11. **Audit completion.** Run `node .agents/skills/orkestrel-harden/scripts/discovery.ts` and rule on every flag and marker it reports, then inspect source/test helper duplication, exports, environment isolation, unexpected text corruption, and the entire diff.
58
- 12. **Verify.** Run the repository-prescribed gates in order and inspect the generated outputs relevant to the request.
59
- 13. **Review by the size gate, never by the author.** Run the review `.agents/orchestration.md` § Size gate names for the change, resolve every required finding, then rerun the affected scoped verification.
57
+ 11. **Audit completion.** Run `node .agents/skills/orkestrel-harden/scripts/discovery.ts` and rule on every flag and marker it reports, run [hardening.md](references/hardening.md) § Audit security and destructive paths, then inspect source/test helper duplication, exports, environment isolation, unexpected text corruption, and the entire diff.
58
+ 12. **Verify scoped.** Run the gates of the touched projects per `.agents/orchestration.md` § Size gate, in the order the package's own chain fixes, and inspect the generated outputs relevant to the request.
59
+ 13. **Review by the size gate, never by the author.** Run the review `.agents/orchestration.md` § Size gate names on the matrix's claims. Rule every finding before any repair: a finding against a claim is repaired within that claim's row; a finding outside the claims blocks only above the release bar, and the review brief names the plan's bar; an above-bar finding outside every claim opens a rescoping the ledger records and the user rules on; every other finding enters the deferral list (`.claude/rules/campaign.md` § Content). Class each repair's remedy per § Size gate (a correction, a design question, or a deferral), and send a finding about a boundary the package does not own to step 14 before any writer starts. Rerun the affected scoped verification after each repair.
60
+ 14. **Hold the bounds.** Before another repair round at one seam, apply the stop step 1 set for it, re-examined against the signals [hardening.md](references/hardening.md) § Hold the package's bounds names. When the stop fires, or when the seam's findings concern a boundary the package does not own, open one design question on the package's dependence on that behavior, record the decision in the commit that makes it and cite that commit in `plan.md`, and route the findings that remain outside the contract to the deferral list. A stop keeps every claim closed and the bar unbroken; a stop that would reopen a claim is a rescoping the user rules on.
61
+ 15. **Verify tree-wide.** After the review closes, run the tree-wide gates once per `.agents/orchestration.md` § Campaign, with the release chain in a fresh clone of the candidate on each reachable supported host, and name the independent receipt per § Acceptance.
60
62
 
61
63
  ## Accept the result
62
64
 
63
65
  Completion requires:
64
66
 
65
- - all requested capabilities implemented or explicitly proven out of scope;
66
- - red-then-green evidence for every repaired defect;
67
+ - every matrix row closed: implemented, repaired with red-then-green evidence, retained, or excluded with its reason, and no row added since step 3 without a recorded rescoping;
68
+ - no finding above the release bar, and every other finding in the deferral list (`.claude/rules/campaign.md` § Content);
69
+ - every stop step 1 set honored as stated, and each design decision step 14 made recorded in the commit that makes it and cited in `plan.md`;
67
70
  - public contract, implementation, tests, guides, and generated outputs aligned;
68
- - no unresolved centralization, wrapper, dependency-reuse, test-discovery, lifecycle, security, or text-integrity finding;
69
- - exact command evidence for every final gate.
71
+ - the centralization, wrapper, dependency-reuse, test-discovery, lifecycle, security, and text-integrity sweeps run, each hit repaired within a row or deferred per the deferral list;
72
+ - the release chain green in a fresh clone of the accepted commit on each reachable supported host, with exact command evidence for every final gate and the independent receipt `.agents/orchestration.md` § Acceptance names.
70
73
 
71
- Passing tests without an adequacy review, and a builder's self-report, are not completion evidence. When every row is closed and the gates are green, stop per `AGENTS.md` § Work loop.
74
+ Passing tests without an adequacy review, and a builder's self-report, are not completion evidence. When every row is closed, no finding stands above the bar, and the gates are green, stop per `AGENTS.md` § Work loop; a finding below the bar reopens nothing.
72
75
 
73
- Report what changed, what evidence proves it, exact test/gate results, and any genuine residual risk.
76
+ Report what changed, what evidence proves it, exact test/gate results, the deferral list, and any genuine residual risk.
@@ -1,37 +1,39 @@
1
1
  # Production hardening
2
2
 
3
- This reference governs the hardening lane: the risk and seam matrix, real-implementation testing, live-service tests, lifecycle pressure, security paths, the test audit, and generated outputs.
3
+ This reference governs the hardening lane: the package's bounds, the risk and seam matrix, real-implementation testing, live-service tests, lifecycle pressure, holding the bounds, security paths, the test audit, and generated outputs.
4
4
 
5
5
  ## Build the risk and seam matrix
6
6
 
7
- List every boundary where assumptions can fail:
7
+ Draw the matrix inside the package's bounds: the contract its types and guide promise and the hosts it supports. A boundary the package crosses but does not own (the host filesystem's locking and handle semantics, a runtime's scheduling, a harness's sandbox, a scanner's hold on a file) enters the matrix only as the contract's promise about it: what the package does when that boundary fails, never how the boundary behaves.
8
+
9
+ List every boundary where the contract's assumptions can fail:
8
10
 
9
11
  - public inputs and option combinations;
10
12
  - empty, missing, minimum, maximum, overflow, `NaN`, infinity, and signed-zero values;
11
13
  - invalid state transitions and repeated lifecycle operations;
12
14
  - partial work, abort, timeout, retry, pause/resume, stop/destroy, and cleanup;
13
15
  - concurrency, reentrancy, ordering, idempotency, fairness, and backpressure;
14
- - filesystem, process, socket, protocol, browser, model, and network boundaries;
16
+ - filesystem, process, socket, protocol, browser, model, and network boundaries, each marked owned or not owned;
15
17
  - malformed or unexpected strings, paths, headers, frames, JSON, prototypes, getters, and proxies;
16
18
  - resource ownership, leaks, teardown, and pressure;
17
- - environment isolation and unsupported-host behavior;
19
+ - environment isolation, and the contract's refusal or degradation on an unsupported host;
18
20
  - serialization, restore, public exports, and consumer ergonomics.
19
21
 
20
- For each applicable seam, state the invariant, failure mode, observable result, and proving test. Omit irrelevant generic cases rather than creating meaningless tests.
22
+ For each applicable seam, state the invariant, the failure mode, the observable result, the proving test, and whether the package owns the boundary. Omit irrelevant generic cases rather than creating meaningless tests.
21
23
 
22
24
  ## Use real implementations
23
25
 
24
26
  Test through public behavior with:
25
27
 
26
- | Seam | The real thing it must be driven with |
27
- | --------------------------------------- | ------------------------------------------------------------------------ |
28
- | Package behavior | Real package classes and composed managers |
29
- | Filesystem | Temporary directories and files |
30
- | Network protocol | Actual local sockets and protocol-faithful fixture servers |
31
- | Browser | An actual Chromium-family browser when the browser is the system |
32
- | Declared dependency | The actual installed dependency |
33
- | External service or model | The real service in its dedicated project when its behavior is the claim |
34
- | Third-party client or protocol consumer | One representative real foreign client, driven end to end |
28
+ | Seam | The real thing it must be driven with |
29
+ | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
30
+ | Package behavior | Real package classes and composed managers |
31
+ | Filesystem | Temporary directories and files |
32
+ | Network protocol | Actual local sockets and protocol-faithful fixture servers |
33
+ | Browser | An actual Chromium-family browser when the browser is the system |
34
+ | Declared dependency | The actual installed dependency |
35
+ | External service or model | The real service in its dedicated project when its behavior is the claim |
36
+ | Third-party client or protocol consumer | Representative real foreign clients of each client class the contract names, driven end to end |
35
37
 
36
38
  A third-party seam is the one case where the package's own tests cannot close the claim:
37
39
  protocol tests prove the protocol, and only a real client of that class proves the
@@ -69,7 +71,17 @@ Exercise:
69
71
  - cancellation propagation and bounded shutdown;
70
72
  - no busy polling, open handles, leaked processes, sessions, pages, files, or listeners.
71
73
 
72
- Use bounded pressure tests that expose coordination defects without making the suite gratuitously slow.
74
+ Set each pressure proof's load and concurrency from the coordination defect it must expose, state them with the reason beside the proof, and re-examine them against the stop signals `.agents/orchestration.md` § Size gate names. `.claude/rules/tests.md` § Expensive proofs owns the repeat count and acceptance under suite load.
75
+
76
+ ## Hold the package's bounds
77
+
78
+ A seam's finding concerns the package when it falsifies a promise the contract makes; it concerns the host when it describes how a boundary the package does not own behaves.
79
+
80
+ - When a finding falsifies a promise, repair it within its row and close the repair with the mutation probe `.agents/orchestration.md` § Size gate names.
81
+ - When a finding describes a host behavior the contract never promised to survive, open one design question on the package's dependence on that behavior: remove the dependence, narrow the promise, or refuse on that host. Never add a mechanism around the behavior.
82
+ - When a finding is outside the bounds and below the release bar, record it in the deferral list (`.claude/rules/campaign.md` § Content), and reopen it only when its trigger fires.
83
+ - Before another round at one seam, weigh a further repair against a design question and re-examine the stop set for that seam against the signals `.agents/orchestration.md` § Size gate names; the hardening lane adds one: findings move from the contract to the host.
84
+ - A seam that reprices on every edit (a count, a timing) is not a seam; drop the claim per the `orkestrel-falsify` skill § End the depth search.
73
85
 
74
86
  ## Audit security and destructive paths
75
87
 
@@ -280,6 +280,10 @@ and no title scheme.
280
280
  - When a refusal changes voice after a markup change, read it as a role or reachability change
281
281
  before treating the element as missing
282
282
  ([layer.md](references/layer.md) → Role vocabulary).
283
+ - Every census phase states the screen state it starts from, measures the pointer route at arrival
284
+ before any key, and proves a focus-presented state (a skip link, a focus tooltip) by its own case.
285
+ - The reachability walk asserts that focusing each control leaves fixed chrome's geometry
286
+ unchanged.
283
287
 
284
288
  ## Declare the transport family
285
289
 
@@ -13,7 +13,7 @@ description: >-
13
13
  | Within one session | subagents, child tasks, and background commands the session launches | launch results and completion notices |
14
14
  | Across sessions | separate top-level sessions on one machine sharing a checkout, the host, or the execution lane | messages that wake the receiving session; one tracked coordination record when no such channel reaches it |
15
15
 
16
- - Read the page for each harness that hosts a lane before its first launch: `references/claude.md`, `references/codex.md`, `references/cursor.md`, or `references/t3.md`. A harness without a page carries no writer or runner lane until § Bring up a harness is answered on a page of its own.
16
+ - Read the page for each harness that hosts a lane before its first launch: `references/claude.md`, `references/codex.md`, `references/cursor.md`, `references/t3.md`, or `references/cloud.md`. A harness without a page carries no writer or runner lane until § Bring up a harness is answered on a page of its own.
17
17
  - Apply `.agents/orchestration.md` for routing, session reuse, consultation, independence, and acceptance.
18
18
 
19
19
  ## Scripts
@@ -26,7 +26,7 @@ Run from the checkout root. The script's opening comment owns its behavior.
26
26
 
27
27
  The host budget counts every lane on the machine: this session's, each peer session's, and the Orchestrator's own commands.
28
28
 
29
- - Set the lane bound in the plan before the first dispatch. Run one process-running lane at a time on the host: tests, checks, builds, browsers, captures, and launchers, the Orchestrator's included. Report to the user before a launch that would start a second. Lanes that run no shell command run beside it.
29
+ - Set the lane bound in the plan before the first dispatch. Run one process-running lane at a time on the host: count as a process-running lane every lane that runs a test, a build, a browser, a capture, or a launcher, the Orchestrator's included; an owned-file format check, lint, type check, or `policy` run that reads only its owned paths' violations runs beside it. Report to the user before a launch that would start a second. Lanes that run no shell command run beside it.
30
30
  - Count running lanes and owned test processes at each launch.
31
31
  - Limit terminal launches: chain commands that do not gate each other into one launch (as a plan for `.agents/skills/orkestrel-dispatch/scripts/chain.ts`), write long output to a file and read it once, never poll with repeated short calls, never retry a run in a loop, and check once for owned leftovers before a launch.
32
32
  - Find the cause of an interrupted run before relaunching it.
@@ -86,8 +86,8 @@ expect: <red or green, named cases, required artifact>
86
86
 
87
87
  - At each applicable phase (types, failing proof, source, and documentation), request the corresponding checks from the runner.
88
88
  - Read a shared region immediately before each small, syntactically complete patch. On a context mismatch, reread and reapply only the owned hunk.
89
- - Keep read-only shell searches within § Bound the host. Send every test, check, lint, format, and build request to the runner.
90
- - Run no formatter. Apply the exact formatting hunk the Orchestrator supplies, then request a read-only format check.
89
+ - Keep read-only shell searches within § Bound the host. A writer runs the read-only checks its charter grants on its owned files (the format check, a non-fix lint, the scoped type check), and, when it edits an instruction file, the `policy` project reading only the violations on its owned paths, as observations and sends every test, build, and tree-wide gate to the runner.
90
+ - Run no formatter. Apply the exact formatting hunk the Orchestrator supplies, then run a read-only format check.
91
91
  - Before a temporary mutation, send the runner a request whose `holds:` names the conflicting commands and each affected writer, and mutate after the command then running returns its result. Restore the exact input, verify the restoration, and release the holds in the next request.
92
92
  - When the unit's required checks pass, send `FINAL <lane>` with source identity and evidence, write the report, and end the turn. Preserve the session for suitable follow-up work.
93
93
 
@@ -140,4 +140,4 @@ Answer each question on the harness's page under `references/`, from measurement
140
140
  10. Capability map: which engine serves each capability of `.agents/orchestration.md` § Roles? Record the map where that section's bullets direct.
141
141
  11. Visibility: which launch channel shows the lane to the user, and can the user stop it there?
142
142
 
143
- A page holds the answers in its § Mechanics table, one row per question, and the field lessons under § Quirks, one "When X, do Y" directive per lesson; a measurement keeps its date. `.agents/transports/<harness>.md` owns a harness's CLI as a bench, and `.agents/platforms/<platform>.md` owns the host shell.
143
+ `references/cloud.md` holds the answers for a cloud sandbox host. A page holds the answers in its § Mechanics table, one row per question, and the field lessons under § Quirks, one "When X, do Y" directive per lesson; a measurement keeps its date. `.agents/transports/<harness>.md` owns a harness's CLI as a bench, and `.agents/platforms/<platform>.md` owns the host shell.
@@ -0,0 +1,28 @@
1
+ # Cloud sandbox as a lane host
2
+
3
+ A cloud sandbox session that runs Claude Code on a remote machine. `.claude/AGENTS.md` § Cloud owns its setup hooks; `.agents/transports/codex.md` owns the Codex sandbox on POSIX and Cloud; `.agents/platforms/` owns the host shell.
4
+
5
+ ## Mechanics
6
+
7
+ A row marked unmeasured carries no lane until a measurement on the host answers it.
8
+
9
+ | Question | Cloud sandbox |
10
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | Start | The parent starts a session through the remote trigger. A subagent cannot load the remote trigger (2026-10-28). |
12
+ | Continue | Unmeasured. |
13
+ | Wake versus deliver | Unmeasured. |
14
+ | Track | The session identity the trigger returns. The parent reads the session's log itself; the log reader truncates a long final report (2026-10-28). |
15
+ | Background | Unmeasured. |
16
+ | Isolation | The sandbox refuses `git checkout`, `clean`, `reset`, `restore`, and `stash drop`, so a lane cannot restore its own checkout; give each trial phase a fresh clone or scratch copy (2026-10-28). |
17
+ | Tools | Shell and file tools inside the sandbox; the git refusals above. The stop hook asks to commit and push (2026-10-28). |
18
+ | Limits | Unmeasured. |
19
+ | Host effects | Unmeasured. |
20
+ | Visibility | Unmeasured. |
21
+ | Capability map | Unmeasured. |
22
+
23
+ ## Quirks
24
+
25
+ - When a trial needs a clean tree, run each phase in a fresh clone or scratch copy; the sandbox refuses `git checkout`, `clean`, `reset`, `restore`, and `stash drop`.
26
+ - When the stop hook asks to commit and push, a dispatched role never commits or pushes, and a peer session's brief says whether it does.
27
+ - When a session's result is needed, the parent reads the session's log itself; a subagent cannot load the remote trigger.
28
+ - When a session's final report may run long, ask in the brief for a short structured summary as the last message; the log reader truncates a long final report.