@orkestrel/scaffold 0.0.121 → 0.0.123
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.
- package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +57 -9
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
- package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +539 -0
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1163 -0
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
- package/dist/bin/main.js +8 -6
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +29 -18
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +7 -6
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +3 -2
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -2
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +3 -2
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +24 -11
- package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +18 -12
- package/dist/host/agents/skills/orkestrel-harden/references/document.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +2 -1
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +4 -4
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +642 -0
- package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +665 -0
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +16 -15
- package/dist/host/agents/skills/orkestrel-parallel/references/{claude.md → claude-code.md} +13 -13
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1433 -0
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +12 -9
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +39 -8
- package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
- package/dist/host/claude/AGENTS.md +2 -2
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/builder.md +1 -1
- package/dist/host/claude/agents/distiller.md +2 -1
- package/dist/host/claude/agents/grok.md +2 -2
- package/dist/host/claude/agents/opus.md +8 -7
- package/dist/host/claude/agents/orkestrel.md +7 -7
- package/dist/host/claude/agents/planner.md +3 -3
- package/dist/host/claude/agents/reviewer.md +3 -3
- package/dist/host/claude/agents/scout.md +2 -1
- package/dist/host/claude/agents/verifier.md +2 -2
- package/dist/host/claude/rules/campaign.md +15 -13
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/names.md +13 -7
- package/dist/host/claude/rules/patterns.md +14 -0
- package/dist/host/claude/rules/quality.md +4 -1
- package/dist/host/claude/rules/tests.md +5 -1
- package/dist/host/claude/rules/workspace.md +9 -0
- package/dist/host/claude/rules/writing.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +6 -6
- package/dist/host/codex/agents/astra.toml +1 -1
- package/dist/host/codex/agents/builder.toml +1 -1
- package/dist/host/codex/agents/distiller.toml +4 -2
- package/dist/host/codex/agents/grok.toml +5 -2
- package/dist/host/codex/agents/opus.toml +6 -4
- package/dist/host/codex/agents/planner.toml +6 -5
- package/dist/host/codex/agents/reviewer.toml +9 -8
- package/dist/host/codex/agents/scout.toml +5 -1
- package/dist/host/codex/agents/verifier.toml +8 -3
- package/dist/host/dotfiles/gitignore +1 -2
- package/dist/host/guides/agent.md +1119 -457
- package/dist/host/guides/ndjson.md +81 -21
- package/dist/host/guides/ollama.md +22 -18
- package/dist/host/guides/probe.md +29 -27
- package/dist/host/guides/scaffold.md +42 -15
- package/dist/host/guides/study.md +538 -450
- package/dist/host/manifest.json +81 -63
- package/dist/host/tests/config.test.ts +7 -0
- package/dist/src/core/index.cjs +14 -8
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -4
- package/dist/src/core/index.d.ts +1 -4
- package/dist/src/core/index.js +14 -8
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +87 -8
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +50 -6
- package/dist/src/server/index.d.ts +50 -6
- package/dist/src/server/index.js +87 -10
- package/dist/src/server/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -38,13 +38,17 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
38
38
|
| `builder` | a fully specified unit with a closed shape, app layer included | closed-shape | sonnet | sol |
|
|
39
39
|
| `checker` | mechanical conformance against criteria and rules | mechanical | haiku | luna |
|
|
40
40
|
| `verifier` | gates and evidence commands, exit-code truth | mechanical | haiku | luna |
|
|
41
|
-
| `scout` | exact bounded lookup
|
|
41
|
+
| `scout` | exact bounded lookup; marking a supplied list against criteria | mechanical | haiku | luna |
|
|
42
42
|
| `distiller` | bulk reading when the Cursor bench is dark | reader | haiku | luna |
|
|
43
43
|
| `researcher` | primary-source research when the Cursor bench is dark | reader | haiku | luna |
|
|
44
44
|
| `orkestrel` | ecosystem reconciliation over supplied evidence | reader | sonnet | sol |
|
|
45
45
|
|
|
46
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
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).
|
|
48
|
+
- A role holding the subjective lane judges whether the requested shape and voice are present, names and boundaries are coherent, the work sits at the right layer, each concept earns its place, and the guide matches the code. A role holding the objective lane judges correctness under adverse orderings, what the contracts and installed declarations permit, dependency and range truth, the missing seam or the assertion that cannot fail, and the letter of the rules. A charter points here for both lenses.
|
|
49
|
+
- In a falsify round, where a claim about a name or a comment is no claim, both lanes hold the same claims and differ by posture: the subjective lane drives the subject as a real caller would and reports what that caller meets, and the objective lane tests the contract's letter across adverse orderings.
|
|
50
|
+
- Read the word `lane` by its qualifier: a subjective or an objective lane is the lens a role holds, a writer, runner, or review lane is a unit at work, and the execution lane is the host resource `.agents/skills/orkestrel-parallel/SKILL.md` § Share an execution lane between sessions orders. Read the word `census` the same way: the `map.ts --census` flag counts a term, the `discovery.ts` script lists test collection, `.agents/skills/orkestrel-harden/references/bindings.md` sweeps a binding key, and a class census under § Depth, breadth, and machinery lists one defect class across packages.
|
|
51
|
+
- `planner` also carries the read-only consultation § Engines admits for Claude Fable 5.1, on the engine the dispatch names.
|
|
48
52
|
- 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.
|
|
49
53
|
- 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.
|
|
50
54
|
- `.agents/transports/<harness>.md` owns each bench's invocation, sandbox, journal, and recovery. `.claude/agents/` and `.codex/agents/` hold one file per role.
|
|
@@ -55,7 +59,9 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
55
59
|
- 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.
|
|
56
60
|
- 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.
|
|
57
61
|
- 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.
|
|
62
|
+
- Route an independent rescore that needs a scorer written from a definition to `astra` in a clean context, blind to the scorer under test; `verifier` runs it into a result file, and `checker` compares that file with the reported table.
|
|
58
63
|
- 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.
|
|
64
|
+
- The Orchestrator runs a release visit and its installing chain, because they install and commit and `verifier` may not. `verifier` reruns the gates on the committed result when § Size gate names them.
|
|
59
65
|
- Record mechanical source adoption as Orchestrator integration or a writer unit. Reserve the runner name for a verifier that made no source repair.
|
|
60
66
|
- 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.
|
|
61
67
|
- 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.
|
|
@@ -100,12 +106,14 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
100
106
|
|
|
101
107
|
- Size the effort to the task before spending: a lookup takes one lane, routed per § Routing, and only open-ended work with independent, high-value parts fans out, per § Parallelism.
|
|
102
108
|
- Locate the evidence with short broad probes before any deep pass: a run of the shipped command, a census, a search. Go deep only on a defect or gap a run has shown, in one lane, with the narrowest instrument that answers it: a counting probe or a mutation.
|
|
109
|
+
- When a defect class can recur across packages, census the class across every package before a review of any one: a script lists the whole population, `scout` marks each listed row against the brief's explicit criteria, and `analyst` or the Orchestrator rules each marked row once and fixes it at its cause. A list made by hand is no population.
|
|
110
|
+
- Set every stop with what reopens it, and record both in the plan. At a re-examination, hold the stop unless a proposal names the condition it meets; a stop that names no condition passes only on the user's ruling. Before a continuation, record whether its unit repairs an admitted row or reopens the stopped seam.
|
|
103
111
|
- When a failure recurs, read the exact input and output of the failing case before adding capability, and fix the cause.
|
|
104
112
|
- Deepen in rounds and report a usable result after each. Stop at the first result that clears the acceptance criteria and name the gaps that remain.
|
|
105
113
|
- Prove a change in one consumer, with its gate green, before spreading it to the rest.
|
|
106
114
|
- Use the simplest method that can clear the criteria, starting with what an `@orkestrel` package already provides, looked up per `AGENTS.md` § Non-negotiable rules. Add machinery only after that method fails a measured check, and build nothing for a hypothetical need.
|
|
107
115
|
- Do a one-use step inline. Keep a tool one unit runs more than once as a throwaway under `tmp/`, deleted with the unit and never committed.
|
|
108
|
-
- When a second unit, package, or campaign needs a tool, move it out of `tmp/`: into a skill script under `.agents/skills/` when it
|
|
116
|
+
- When a second unit, package, or campaign needs a tool, move it out of `tmp/`: into a skill script under `.agents/skills/` when it runs a procedure, with a mirrored proof for each correctness claim it carries, and into its own package, with its own tests and release, when a consumer imports it or pins, replays, or audits an identity it publishes. Write the promotion path and the removal path when you first build it.
|
|
109
117
|
- When a throwaway grows a mechanism per step instead of answering its question, stop and map it against the owning packages before building more.
|
|
110
118
|
- Ship the proven fix first, and run experiments behind it under a stated cap.
|
|
111
119
|
|
|
@@ -124,7 +132,7 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
124
132
|
- 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.
|
|
125
133
|
- 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.
|
|
126
134
|
- 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.
|
|
127
|
-
- 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.
|
|
135
|
+
- 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 per § Depth, breadth, and machinery, 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.
|
|
128
136
|
- 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.
|
|
129
137
|
- An all-confirmed round ends the audit. A round needs an added or repaired claim to test; reviewer appetite is not a subject.
|
|
130
138
|
|
|
@@ -132,9 +140,9 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
132
140
|
|
|
133
141
|
A large change opens with a concise goal and its exit criterion, short enough to serve as a goal prompt. It runs these phases once each, in order, and ends when that exit criterion is met.
|
|
134
142
|
|
|
135
|
-
1. **Absorb.** Map the terrain with the `orkestrel-scout` skill's `map.ts`, then `grok` distills it and the prior art. In an Orkestrel repository, `verifier` or another tool-capable role collects manifests, lockfiles, installed declarations, and registry readings, and `orkestrel` reconciles them.
|
|
136
|
-
2. **Design.** One independent round: `planner` (subjective) and `analyst` (objective) on one brief, clean contexts, blind to each other. Reconcile into one plan: units, owned files, dependencies, parallel and serial order, acceptance criteria, exit criterion, ledger.
|
|
137
|
-
3. **Implement.** Dispatch units per § Routing and § Parallelism.
|
|
143
|
+
1. **Absorb.** Map the terrain with the `orkestrel-scout` skill's `map.ts`, then `grok` distills it and the prior art. In an Orkestrel repository, `verifier` or another tool-capable role collects manifests, lockfiles, installed declarations, and registry readings, and `orkestrel` reconciles them. Read `.agents/skills/orkestrel-harden/references/methods.md` and select the methods its selector names for each package kind and scenario in scope.
|
|
144
|
+
2. **Design.** One independent round: `planner` (subjective) and `analyst` (objective) on one brief, clean contexts, blind to each other. Reconcile into one plan: units, owned files, dependencies, parallel and serial order, acceptance criteria, exit criterion, governing skills, claims, release bar, a stop per seam, deferral list, ledger. `.agents/skills/orkestrel-harden/SKILL.md` § Execute the workflow, in the step that sets the claims, the release bar, and the deferral list, owns what those hold, across packages as for one, and every review brief names the plan's bar.
|
|
145
|
+
3. **Implement.** Dispatch units per § Routing and § Parallelism. Before the first review round, run one real consumer of the composed result end to end, in the form `.agents/skills/orkestrel-harden/SKILL.md` § Run a real consumer fixes. When the campaign serves a requested product, keep that product runnable beside every later unit.
|
|
138
146
|
4. **Integrate.** Apply returned patches to shared files serially with `node .agents/skills/orkestrel-dispatch/scripts/patch.ts EDITS.md --plan`, then `--apply`. A type, mechanism, or criterion found here is a successor unit, never an integration edit.
|
|
139
147
|
5. **Audit.** One `orkestrel-falsify` round on the integrated result, an independent reviewer per § Engines in each lane; add `checker` when the criteria are mechanical.
|
|
140
148
|
6. **Verify.** `verifier` runs the tree-wide gates once.
|
|
@@ -159,7 +167,9 @@ A large change opens with a concise goal and its exit criterion, short enough to
|
|
|
159
167
|
- Restrict read-only roles to read tools when the harness supports that restriction. Otherwise state the read-only boundary in the brief and record its enforcement limit. The Orchestrator supplies the diff and status to every review dispatch.
|
|
160
168
|
- Permit a verifier to write its assigned evidence artifacts and the generated outputs its dispatch declares; never permit source repairs. A declaration names the command and each path the command writes or replaces. Declare a path only when the command regenerates it and no lane authors it, such as a build directory or a generated inventory file; an authored path is source, whichever command rewrites it. Declare no path for a command that only deletes. Keep each declared output outside every other lane's owned files and recorded fixtures, and hold it with the command's inputs for the run. Under this floor, the declared command can remove and rewrite its declared outputs, and that replacement is neither a destructive command nor a deletion.
|
|
161
169
|
- Record `git status --porcelain` before and after a declared command. Report each declared output that git tracks and the run changed; never revert it. When the run changed a path outside its declarations, stop and report the path.
|
|
162
|
-
- No role
|
|
170
|
+
- No role pushes, tags, publishes, or runs a destructive command, and § Acceptance holds the Orchestrator's push and publication. Only the Orchestrator commits and installs, apart from a writer committing inside a branch, clone, copy, or worktree its brief names, which § Parallelism folds back uncommitted.
|
|
171
|
+
- Before a unit runs a command, name in its brief the services and data the command reaches, through setup imports and informational invocations included: a bare `vitest` run evaluates the `service` project's setup files, and `ollama --version` contacts the server.
|
|
172
|
+
- No lane, the Orchestrator included, runs `npm exec` or `npx` for a package the checkout does not install, because npm then fetches and runs the registry package of that name.
|
|
163
173
|
- No role, the Orchestrator included, runs `git checkout`, `git restore`, `git stash`, `git reset`, or `git clean`. Undo an edit by rewriting the text. Supply an untracked review input by its path; never stage it for review.
|
|
164
174
|
- No role, the Orchestrator included, reads, prints, copies, uploads, or packages a secret: `.env*`, `.npmrc`, `auth.json`, keys, tokens, `CURSOR_API_KEY`.
|
|
165
175
|
- A unit writes only under its owned files, its checkout's `tmp/`, and the declared outputs the preceding bullets permit. The Orchestrator's own briefs, probes, drafts, and records live in the checkout's `tmp/` too, never in a directory outside the repository; the user follows the work through the tree.
|
|
@@ -170,15 +180,16 @@ A large change opens with a concise goal and its exit criterion, short enough to
|
|
|
170
180
|
|
|
171
181
|
Every working file lives under the checkout's gitignored `tmp/`, in the directory its kind names.
|
|
172
182
|
|
|
173
|
-
| Directory | Holds
|
|
174
|
-
| ------------------------------------------ |
|
|
175
|
-
| `tmp/claude/`, `tmp/codex/`, `tmp/cursor/` | bench briefs, launch scripts, journals, `.err` files, last-message files, login logs, per harness
|
|
176
|
-
| `tmp/units/` | native unit briefs, reports, claims files, and unit records
|
|
177
|
-
| `tmp/probes/` | runtime probes the `probe` Vitest project collects and the `probe` MCP server arms, and a skill script's scratch under its own subdirectory (`census/`, `lint/`, `mutate/`)
|
|
178
|
-
| `tmp/type/` | the type stage's workspace mirror, owned by `@orkestrel/probe`
|
|
179
|
-
| `tmp/captures/` | screenshots, resolved-style snapshots, and other capture portfolios
|
|
180
|
-
| `tmp/browsers/` | the journeys a `browse` server saves, their runs and captures, and its profiles under `.profiles/`
|
|
181
|
-
| `tmp/
|
|
183
|
+
| Directory | Holds |
|
|
184
|
+
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
185
|
+
| `tmp/claude/`, `tmp/codex/`, `tmp/cursor/` | bench briefs, launch scripts, journals, `.err` files, last-message files, login logs, per harness |
|
|
186
|
+
| `tmp/units/` | native unit briefs, reports, claims files, and unit records |
|
|
187
|
+
| `tmp/probes/` | runtime probes the `probe` Vitest project collects and the `probe` MCP server arms, and a skill script's scratch under its own subdirectory (`census/`, `lint/`, `mutate/`) |
|
|
188
|
+
| `tmp/type/` | the type stage's workspace mirror, owned by `@orkestrel/probe` |
|
|
189
|
+
| `tmp/captures/` | screenshots, Vitest's `page.screenshot()` captures under `screenshots/` included, resolved-style snapshots, and other capture portfolios |
|
|
190
|
+
| `tmp/browsers/` | the journeys a `browse` server saves, their runs and captures, and its profiles under `.profiles/` |
|
|
191
|
+
| `tmp/studies/` | the results, closures, gradings, labels, scratch, and run records the `@orkestrel/study` executable writes under `tmp/studies/<id>`, its default output, and the study data a consumer keeps out of its tracked tree; outside the directories `sweep.ts --tmp` deletes from |
|
|
192
|
+
| `tmp/worktrees/` | worktrees the Orchestrator creates for a parallel writer |
|
|
182
193
|
|
|
183
194
|
## .orkestrel layout
|
|
184
195
|
|
|
@@ -206,7 +217,7 @@ The Orchestrator triages: obvious correction → tighten and re-dispatch; missin
|
|
|
206
217
|
## Benches
|
|
207
218
|
|
|
208
219
|
- Probe a bench with the dispatch skill's `scripts/bench.ts` and the model its transport pins before its first lane in a session. A version string or a login status is not liveness.
|
|
209
|
-
- For a harness that uses a bench, record a dispatch that fails on auth, quota, model access, or network as bench dark and re-plan the lane: Astra bench dark →
|
|
220
|
+
- For a harness that uses a bench, record a dispatch that fails on auth, quota, model access, or network as bench dark and re-plan the lane: Astra bench dark → `opus` takes `astra`'s units, and `planner` takes `analyst`'s design arguments and `reviewer` its audits, each holding the objective lane on Claude Opus; when the unit under review was written on Claude Opus, dispatch `reviewer` with `model: sonnet`; Claude Opus bench dark → Astra holds the subjective lane too; Grok dark → the harness's native reader, `distiller` or `researcher`: Claude Haiku 5.5 in Claude Code, GPT-6 Luna under the Codex mapping. When Haiku refuses the read, re-dispatch the role with `model: sonnet`. Record every substitution in the brief and in the commit that carries the unit. For a native role failure, use § Deviation protocol without a Claude fallback prerequisite.
|
|
210
221
|
- Never assign Grok a design or review lane in Claude Code or Codex.
|
|
211
222
|
- Journal every bench run under `tmp/<bench>/` with its session id. Never commit a journal.
|
|
212
223
|
|
|
@@ -234,5 +245,5 @@ The Orchestrator triages: obvious correction → tighten and re-dispatch; missin
|
|
|
234
245
|
- Before calling work ready, try the shipped result as the user will, on the build they run, and report what did not run.
|
|
235
246
|
- Substitute an engine only when the same session recorded the bench dark; name the fallback in the brief and the carrying commit.
|
|
236
247
|
- In a repository whose package the registry already serves, commit on the main branch and push it only on the user's go-ahead.
|
|
237
|
-
- 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
|
|
248
|
+
- 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 imports a name that no registry-served version within its committed ranges carries, a name only an unpublished local pin carries included. Push a commit only after the gate run on that commit, or record the push as ungated.
|
|
238
249
|
- Publishing is the user's decision and credential; `orkestrel-publish` owns the release procedure, the bump rules, and the dependency-tarball rules.
|
|
@@ -13,25 +13,26 @@ description: >-
|
|
|
13
13
|
| Script | Does |
|
|
14
14
|
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
15
|
| `scripts/bench.ts` | `--cursor [--resolve]`, `--codex [--sandbox MODE]`, or `--claude`, each with `[--model ID] [--cap SECONDS]`: resolves the bench entry, reads its version and login, runs one bounded round trip into `tmp/<bench>/bench.jsonl`, and prints JSON with `live`; `--resolve` prints the Cursor entry alone. A malformed cap, a `--sandbox` outside `read-only`, `workspace-write`, and `danger-full-access`, or `--resolve` without `--cursor` is a usage fault, never a dark bench. Exit 3 when the bench is dark, 64 on usage. |
|
|
16
|
-
| `scripts/brief.ts` | `--unit UNIT --lane units\|cursor\|codex\|claude [--subject TEXT]` writes the brief from `.agents/templates/brief.md` and never overwrites a launched one; `--check PATH` lists every slash-bearing path the brief names that does not resolve from the root. Exit 3 when
|
|
16
|
+
| `scripts/brief.ts` | `--unit UNIT --lane units\|cursor\|codex\|claude [--subject TEXT]` writes the brief from `.agents/templates/brief.md` and never overwrites a launched one; `--check PATH` lists every slash-bearing path the brief names that does not resolve from the root, and names the `## Role and engine` section or the `## Execution` section's spawn-nothing sentence when the brief omits it. Exit 3 when a path or a section is missing. |
|
|
17
17
|
| `scripts/launch.ts` | `--journal PATH --errors PATH --cap SECONDS [--status] -- COMMAND [ARGS...]` runs the command with no shell and closed stdin, kills it at the cap (its process tree on Windows), records `git status --porcelain` before and after with `--status`, prints a spawn line carrying the `pid` when the command starts, writes that pid to `<journal>.pid`, and ends the errors file with `exit=`. Exit 124 when capped; 127 when the command cannot start (the errors file names why); 64 on usage, including a cap above 2147483 seconds. |
|
|
18
18
|
| `scripts/login.ts` | `--codex [--cap SECONDS]` reads `codex login status`, runs `codex login --device-auth` journaled to `tmp/codex/login.log` when it is not logged in, prints the URL and the one-time code as they appear, and polls the status until it answers or the cap ends, ending any status read that outlasts the cap, and refuses a cap above 2147483 seconds; `--claude` reads `claude auth status`. Exit 0 logged in, 3 not. |
|
|
19
19
|
| `scripts/result.ts` | `--cursor\|--claude\|--codex JOURNAL [--out PATH]` prints the session id, the answer length, the run's `exit`, `capped`, and `durationMs` from the errors file, and the journal's `bytes`, `ageMs`, and `lastEvent`. Exit 3 when the journal carries no session or answer. |
|
|
20
20
|
| `scripts/cite.ts` | `PATH [--root DIR] [--json]` lists every `file:line` citation in a report whose file does not exist or whose line is past the end. Exit 3 when one does not resolve. |
|
|
21
21
|
| `scripts/sweep.ts` | `--report` lists leftovers under `tmp/` and `.orkestrel/` by age, deletes nothing, and flags a `.orkestrel/**/*.md` line that cites a backticked path git ignores or names a machine path; `--tmp [--older-than MINUTES]` deletes stale launch files and refuses while a journal is changing; `--unit UNIT [--delete]` lists or deletes one accepted unit's brief, report, claims, journal, errors, status, pid, and last-message files; `--tmp` and `--unit --delete` keep every file git tracks and print `kept tracked <path>`. |
|
|
22
|
-
| `scripts/chain.ts` | `--plan FILE.json --journal DIR` runs the steps of a JSON plan (`name`, `command`, `args`, optional `cwd` and `env`) in order with no shell, writes each step's output to `<journal>/<name>.txt`, prints one `name exit= durationMs=` line per step, and stops at the first step that does not exit 0. Exit is that step's code; 2 when a step cannot start; 64 on usage.
|
|
22
|
+
| `scripts/chain.ts` | `--plan FILE.json --journal DIR` runs the steps of a JSON plan (`name`, `command`, `args`, optional `cwd` and `env`, an `env` name dropping every inherited variable whose lower-cased name it claims) in order with no shell, writes each step's output to `<journal>/<name>.txt`, prints one `name exit= durationMs=` line per step, and stops at the first step that does not exit 0. Exit is that step's code; 2 when a step cannot start; 64 on usage. |
|
|
23
23
|
| `scripts/patch.ts` | `EDITS.md (--plan \| --apply) [--skip N ...]` applies an edit file of `### <path>` blocks, each with a `reason:` line and fenced `old:` and `new:` texts: every `old` text must occur exactly once in its file after the earlier edits to that file (however the blocks spell its path), and nothing is written unless every selected edit resolves. `--plan` prints each edit's resolution; `--skip N` leaves out edit N and repeats. Exit 1 when an edit does not resolve, 64 on usage. |
|
|
24
24
|
|
|
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. Cite each law by file and section; quote a law the brief carries, never paraphrase it. 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. 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.
|
|
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.
|
|
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. Class a failure that passes when rerun alone by its cause: contention from a peer session is a host limit; contention from the session's own concurrent lanes breaks `.agents/skills/orkestrel-parallel/SKILL.md` § Bound the host, and the step reruns alone within that bound; any other failure that passes alone is an order-dependent defect to diagnose, never a timing miss to record. An unchanged rerun of the sequence that produced the failure 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. Name each owned path with the rule that places it, preflight every path the unit will need once before the brief ships, and refuse a catch-all ownership line. A file grant authorizes no package: name each one the unit may add with the user's ruling. 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
30
|
4. Order acceptance criteria cheap-first, per `AGENTS.md` § Work loop: regenerate, then the format check, lint, and type check, then scoped tests. 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
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
|
-
7.
|
|
34
|
-
8.
|
|
33
|
+
7. Word a review brief per `.claude/rules/writing.md` § Substitutions and the review-wording quirk in the `orkestrel-parallel` skill's reference Codex as a lane host.
|
|
34
|
+
8. Fill each placeholder at its value sites only; a global replace also rewrites a stop clause that names the placeholder.
|
|
35
|
+
9. Run `brief.ts --check <brief>` and fix every missing path and omitted section before the launch.
|
|
35
36
|
|
|
36
37
|
When a unit may attribute a failed command to its baseline, require its pre-edit output, exit code,
|
|
37
38
|
and input identity before writing; otherwise report the attribution as unverified.
|
|
@@ -6,6 +6,7 @@ Apply these rules to every command that outlives the turn that starts it: a benc
|
|
|
6
6
|
|
|
7
7
|
- Launch as a harness-tracked background command through `scripts/launch.ts` under a hard cap, per § Launch ownership.
|
|
8
8
|
- Spawn a package manager through its JavaScript entry; `.agents/platforms/<platform>.md` names the entry and the shell quirks of each host.
|
|
9
|
+
- When a chain's scripts must run on a selected Node, launch the chain under a `PATH` that leads with that Node's directory: npm resolves a script's `node` from `PATH` and adds no directory of the Node running it.
|
|
9
10
|
- Write a multi-step chain as a TypeScript file run by `node`, with an opening comment naming its log and its cap. Never edit a script while it runs: copy, edit the copy, launch the copy.
|
|
10
11
|
- Run the first use of any flag, subcommand, or quoting form in a throwaway probe, never inside a unit.
|
|
11
12
|
- Keep network-dependent work (installs, lockfile generation, live fetches) out of sandboxed bench execs.
|
|
@@ -27,9 +28,9 @@ Apply these rules to every command that outlives the turn that starts it: a benc
|
|
|
27
28
|
|
|
28
29
|
- Take the child's `pid` from the spawn line `scripts/launch.ts` prints when the command starts, or from `<journal>.pid`. Never take it from a pattern match over command lines, and never run `pgrep -f` or `pkill -f`.
|
|
29
30
|
- 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
|
-
- 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
|
+
- 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. A run under `.agents/skills/orkestrel-parallel/scripts/lane.ts` kills and checks the remaining descendants itself; on its exit 70, list and kill by hand before another command starts.
|
|
31
32
|
- 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
|
-
- Rerun a failure alone only after the unit exits,
|
|
33
|
+
- Rerun a failure alone only after the unit exits, and class the reading per `.agents/skills/orkestrel-dispatch/SKILL.md` § Write the brief; a unit's own rerun is never alone.
|
|
33
34
|
|
|
34
35
|
## Cap
|
|
35
36
|
|
|
@@ -8,9 +8,10 @@
|
|
|
8
8
|
// edited. The second form reads every backticked token carrying a slash (a backslash counts and is
|
|
9
9
|
// read as a slash), strips a `:line` or
|
|
10
10
|
// `:line-line` suffix, resolves it from the working directory, and prints the ones that do not
|
|
11
|
-
// exist; a bare filename is outside the check.
|
|
12
|
-
//
|
|
13
|
-
//
|
|
11
|
+
// exist; a bare filename is outside the check. It also names each template section the brief omits:
|
|
12
|
+
// the `## Role and engine` section, and the `## Execution` section with its spawn-nothing sentence.
|
|
13
|
+
// The two forms are two modes; name one. The script refuses a flag it does not read, the
|
|
14
|
+
// `--flag=value` form included. Exit 3 when a path or a section is missing, 64 on usage.
|
|
14
15
|
import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
|
|
15
16
|
import { dirname, join, resolve } from 'node:path'
|
|
16
17
|
import { fileURLToPath } from 'node:url'
|
|
@@ -33,6 +34,18 @@ export const LANES: Readonly<Record<string, string>> = Object.freeze({
|
|
|
33
34
|
claude: 'tmp/claude',
|
|
34
35
|
})
|
|
35
36
|
|
|
37
|
+
/** Describes a template section a brief must keep: its heading and the sentence it must carry. */
|
|
38
|
+
export interface Requirement {
|
|
39
|
+
readonly heading: string
|
|
40
|
+
readonly sentence: string | undefined
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Lists the template sections every brief must keep, in template order. */
|
|
44
|
+
export const REQUIREMENTS: readonly Requirement[] = [
|
|
45
|
+
{ heading: '## Role and engine', sentence: undefined },
|
|
46
|
+
{ heading: '## Execution', sentence: 'Perform the assignment yourself and spawn nothing.' },
|
|
47
|
+
]
|
|
48
|
+
|
|
36
49
|
/** Lists the flags that take a value. */
|
|
37
50
|
export const VALUE_FLAGS: readonly string[] = ['--unit', '--lane', '--subject', '--check']
|
|
38
51
|
|
|
@@ -125,6 +138,44 @@ export function extractPaths(content: string): readonly string[] {
|
|
|
125
138
|
return [...found].sort()
|
|
126
139
|
}
|
|
127
140
|
|
|
141
|
+
/**
|
|
142
|
+
* Reads the body of a level-two section.
|
|
143
|
+
*
|
|
144
|
+
* @param content - The brief text.
|
|
145
|
+
* @param heading - The heading line, such as `## Execution`.
|
|
146
|
+
* @returns The text between the heading line and the next level-two heading or the end, or
|
|
147
|
+
* undefined when no line equals the heading.
|
|
148
|
+
*/
|
|
149
|
+
export function extractSection(content: string, heading: string): string | undefined {
|
|
150
|
+
const lines = content.split(/\r\n|\n/u)
|
|
151
|
+
const start = lines.findIndex((line) => line.trimEnd() === heading)
|
|
152
|
+
if (start === -1) return undefined
|
|
153
|
+
const rest = lines.slice(start + 1)
|
|
154
|
+
const end = rest.findIndex((line) => line.startsWith('## '))
|
|
155
|
+
return (end === -1 ? rest : rest.slice(0, end)).join('\n')
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Names each required template section a brief omits.
|
|
160
|
+
*
|
|
161
|
+
* @param content - The brief text.
|
|
162
|
+
* @param requirements - The sections the brief must keep.
|
|
163
|
+
* @returns One description per omission, in requirement order: the heading when its section is
|
|
164
|
+
* absent, and the sentence with its heading when the section is present without it.
|
|
165
|
+
*/
|
|
166
|
+
export function scanOmissions(
|
|
167
|
+
content: string,
|
|
168
|
+
requirements: readonly Requirement[],
|
|
169
|
+
): readonly string[] {
|
|
170
|
+
return requirements.flatMap(({ heading, sentence }) => {
|
|
171
|
+
const body = extractSection(content, heading)
|
|
172
|
+
const named = sentence === undefined ? '' : ` with the sentence ${JSON.stringify(sentence)}`
|
|
173
|
+
if (body === undefined) return [`the ${JSON.stringify(heading)} section${named}`]
|
|
174
|
+
if (sentence === undefined || body.replace(/\s+/gu, ' ').includes(sentence)) return []
|
|
175
|
+
return [`the sentence ${JSON.stringify(sentence)} under ${JSON.stringify(heading)}`]
|
|
176
|
+
})
|
|
177
|
+
}
|
|
178
|
+
|
|
128
179
|
/**
|
|
129
180
|
* Resolves the first brief path for a unit that no file occupies.
|
|
130
181
|
*
|
|
@@ -168,27 +219,32 @@ export function writeBrief(argv: readonly string[]): number {
|
|
|
168
219
|
}
|
|
169
220
|
|
|
170
221
|
/**
|
|
171
|
-
* Checks that every path a brief names exists.
|
|
222
|
+
* Checks that every path a brief names exists and that the brief keeps every required section.
|
|
172
223
|
*
|
|
173
224
|
* @param path - The brief file.
|
|
174
|
-
* @returns The exit code: 0 when every path exists
|
|
225
|
+
* @returns The exit code: 0 when every path exists and no section is omitted, 3 when a path is
|
|
226
|
+
* missing or a section is omitted, 64 when the brief is not a file.
|
|
175
227
|
*/
|
|
176
228
|
export function checkBrief(path: string): number {
|
|
177
229
|
if (!existsSync(path) || !statSync(path).isFile()) {
|
|
178
230
|
console.error(`brief: ${path} is not a file`)
|
|
179
231
|
return 64
|
|
180
232
|
}
|
|
181
|
-
const
|
|
233
|
+
const content = readFileSync(path, 'utf8')
|
|
234
|
+
const paths = extractPaths(content)
|
|
182
235
|
const missing = paths.filter((candidate) => !existsSync(resolve(candidate)))
|
|
183
|
-
|
|
184
|
-
|
|
236
|
+
const omitted = scanOmissions(content, REQUIREMENTS)
|
|
237
|
+
console.log(JSON.stringify({ brief: path, checked: paths.length, missing, omitted }))
|
|
238
|
+
if (omitted.length > 0) console.error(`brief: ${path} omits ${omitted.join('; ')}`)
|
|
239
|
+
return missing.length === 0 && omitted.length === 0 ? 0 : 3
|
|
185
240
|
}
|
|
186
241
|
|
|
187
242
|
/**
|
|
188
243
|
* Runs the script on its arguments.
|
|
189
244
|
*
|
|
190
245
|
* @param argv - The arguments after the script path.
|
|
191
|
-
* @returns The exit code: 0 on success, 3 when a named path is missing, 64 on
|
|
246
|
+
* @returns The exit code: 0 on success, 3 when a named path or a required section is missing, 64 on
|
|
247
|
+
* usage.
|
|
192
248
|
*/
|
|
193
249
|
export function main(argv: readonly string[]): number {
|
|
194
250
|
const unknown = readUnknownFlags(argv, FLAGS)
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
// node .agents/skills/orkestrel-dispatch/scripts/chain.ts --plan FILE.json --journal DIR
|
|
3
3
|
// The plan is a JSON array of steps, each `{ "name": "...", "command": "...", "args": ["..."] }`
|
|
4
4
|
// with an optional `"cwd"` (a directory, relative to the working directory) and `"env"` (a record
|
|
5
|
-
// of strings laid over this process's environment
|
|
5
|
+
// of strings laid over this process's environment by case-folded name, so an added variable drops
|
|
6
|
+
// every inherited one whose lower-cased name it claims). A step name is letters, digits, dots,
|
|
6
7
|
// underscores, and hyphens, opens with a letter or digit, and is unique in the plan. Each step runs
|
|
7
8
|
// with no shell and closed stdin, in plan order, with its standard output and standard error
|
|
8
9
|
// written together to `DIR/<name>.txt`; the script prints one `name exit=N durationMs=N` line per
|
|
@@ -235,6 +236,31 @@ export function readStep(entry: unknown): readonly Step[] {
|
|
|
235
236
|
]
|
|
236
237
|
}
|
|
237
238
|
|
|
239
|
+
/**
|
|
240
|
+
* Lays added variables over an inherited environment by case-folded name.
|
|
241
|
+
*
|
|
242
|
+
* @remarks
|
|
243
|
+
* A Windows environment block folds names by case, so an inherited `NPM_CONFIG_CACHE` would
|
|
244
|
+
* outrank an added `npm_config_cache`; every inherited variable whose lower-cased name an added
|
|
245
|
+
* variable claims is dropped first.
|
|
246
|
+
*
|
|
247
|
+
* @param inherited - The environment the child would inherit.
|
|
248
|
+
* @param added - The variables the step sets.
|
|
249
|
+
* @returns The inherited variables no added name claims, followed by the added variables.
|
|
250
|
+
*/
|
|
251
|
+
export function mergeEnv(
|
|
252
|
+
inherited: Readonly<Record<string, string | undefined>>,
|
|
253
|
+
added: Readonly<Record<string, string>>,
|
|
254
|
+
): Record<string, string | undefined> {
|
|
255
|
+
const claimed = new Set(Object.keys(added).map((name) => name.toLowerCase()))
|
|
256
|
+
return {
|
|
257
|
+
...Object.fromEntries(
|
|
258
|
+
Object.entries(inherited).filter(([name]) => !claimed.has(name.toLowerCase())),
|
|
259
|
+
),
|
|
260
|
+
...added,
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
|
|
238
264
|
/**
|
|
239
265
|
* Runs one step with no shell, its output and errors written together to a file.
|
|
240
266
|
*
|
|
@@ -249,7 +275,7 @@ export function runStep(step: Step, output: string): Finish {
|
|
|
249
275
|
try {
|
|
250
276
|
const result = spawnSync(step.command, step.args, {
|
|
251
277
|
cwd: step.cwd === undefined ? undefined : resolve(step.cwd),
|
|
252
|
-
env:
|
|
278
|
+
env: mergeEnv(process.env, step.env),
|
|
253
279
|
stdio: ['ignore', descriptor, descriptor],
|
|
254
280
|
windowsHide: true,
|
|
255
281
|
shell: false,
|
|
@@ -29,7 +29,8 @@ Read `references/brief.md` for the claim form.
|
|
|
29
29
|
- Derive claims from adverse conditions: cancellation, restart, concurrency, partial failure, malformed or unexpected input, resource exhaustion, orderings the happy path never reaches.
|
|
30
30
|
- Limit claims to the public contract and the risky seams. A claim about a comment or a name is not a claim.
|
|
31
31
|
- Supply the evidence the subject type requires: a code change carries the actual diff and `git status --porcelain`; a rendered surface carries its capture portfolio with source as corroboration; a proposal carries the proposal, the canon it must satisfy, and its motivation.
|
|
32
|
-
- Name
|
|
32
|
+
- Name each claim's settling row: a concrete input through a public call whose output decides the claim.
|
|
33
|
+
- Name the folder under `tmp/probes/` where a lane with a shell writes its probes. It edits no source, runs each probe under `.agents/skills/orkestrel-parallel/SKILL.md` § Bound the host, and deletes the folder before returning.
|
|
33
34
|
- Name the stakes: what this round decides.
|
|
34
35
|
- A successor brief carries what the previous round closed and adds claims against that round's rulings.
|
|
35
36
|
|
|
@@ -37,7 +38,7 @@ Read `references/brief.md` for the claim form.
|
|
|
37
38
|
|
|
38
39
|
- Medium: one lane, with an independent reviewer per `.agents/orchestration.md` § Engines. Large: the objective lane and the subjective lane, same claims file, each in a clean context, neither shown the other's answer before reconciliation. Add `checker` when criteria are mechanical.
|
|
39
40
|
- Tell a lane when its own engine wrote the half it audits.
|
|
40
|
-
- Give a lane the evidence a read-only allowlist cannot produce: run the probe yourself, record its control and output, and hand it over. Run a mutation probe with `scripts/mutate.ts`; its JSON line carries both exits.
|
|
41
|
+
- Give a lane with no shell the evidence a read-only allowlist cannot produce: run the probe yourself, record its control and output, and hand it over. Run a mutation probe with `scripts/mutate.ts`; its JSON line carries both exits.
|
|
41
42
|
- Auditors edit no source and spawn nothing. Their reports are immutable after they return.
|
|
42
43
|
|
|
43
44
|
## Verdict shape
|
|
@@ -55,6 +56,7 @@ Before confirming a claim about a proof, the lane names the mutation that would
|
|
|
55
56
|
|
|
56
57
|
Read `references/reconcile.md`.
|
|
57
58
|
|
|
59
|
+
- Dispatch one settling lane, `verifier` or another lane with a shell, when a claim stays `UNRESOLVED`, with exactly the claim's settling rows. It runs each input through its public call and reports each output. It collects evidence, so it is no further judgment lane under `.agents/orchestration.md` § Parallelism, and you still rule.
|
|
58
60
|
- Reproduce every `BROKEN` and every outside finding yourself before acting on it.
|
|
59
61
|
- Run `node .agents/skills/orkestrel-dispatch/scripts/cite.ts <verdict>` and discard a verdict whose citation does not resolve, then sample that lane's other citations.
|
|
60
62
|
- Treat lane disagreement as answers to different questions; find each question.
|
|
@@ -10,7 +10,7 @@ Give every claims brief these rows.
|
|
|
10
10
|
- **What the round decides.** One sentence, such as "this decides whether the package is bumped and consumed downstream" or "this decides whether the fix is accepted".
|
|
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
|
-
- **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.
|
|
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, and the settling row `SKILL.md` § Write the claims requires. 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
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.
|
|
15
15
|
- **Unknowns.** What the Orchestrator does not know that the round needs, and how the lane reports on it.
|
|
16
16
|
|
|
@@ -18,7 +18,8 @@ Give every claims brief these rows.
|
|
|
18
18
|
|
|
19
19
|
- Give a lane every row of § Rows plus **Role and lane** (the role, its engine, which lane it holds) and **Output** (the verdict shape and its single terminal line from `SKILL.md` § Verdict shape).
|
|
20
20
|
- Omit the writer rows: owned, shared, and off-limits files; acceptance criteria stated as gate commands. Keep the sentence that the lane performs the assignment itself and spawns nothing.
|
|
21
|
-
-
|
|
21
|
+
- Supply a lane with no shell each receipt a claim needs (the command, its input identity, and its exit). Give a lane with a shell the probe folder `SKILL.md` § Write the claims names. Hand no lane a gate criterion.
|
|
22
|
+
- Keep the verdict shape `SKILL.md` § Verdict shape fixes; replace it only when a skill the dispatch names fixes another.
|
|
22
23
|
|
|
23
24
|
## The successor brief
|
|
24
25
|
|
|
@@ -7,7 +7,7 @@ description: Research, audit, refactor, implement, centralize, test, document, a
|
|
|
7
7
|
|
|
8
8
|
## Read
|
|
9
9
|
|
|
10
|
-
`AGENTS.md` § Authority and loading names the files every unit reads. This skill adds the references the selected
|
|
10
|
+
`AGENTS.md` § Authority and loading names the files every unit reads. This skill adds the references the selected phases name, the contracts, barrels, manifest, and configuration those phases need, and every decision-bearing implementation file the user names, read first-hand by the decision owner. Delegate bulk reconnaissance and supporting research, never the design decision. Preserve dirty and user-owned work.
|
|
11
11
|
|
|
12
12
|
## Scripts
|
|
13
13
|
|
|
@@ -16,14 +16,15 @@ Run each from the checkout root. Each script's opening comment owns its behavior
|
|
|
16
16
|
- `scripts/discovery.ts [--config vite.config.ts] [--projects a,b] [--json]` censuses which project collects each test file and which root script chain (a gate) reaches each project. It needs `npm ci` first. It flags a project whose tests no gate lists (ungated), a chained project that collects nothing (empty), and a test or spec file under `tests/` that no project collects and no `node` command runs (undiscovered). It reports without a flag the marker counts per file (`.todo`, `.skipIf`, `.runIf`, `.fails`, a `retry` or timeout option, a numeric timeout argument; `vitest/no-focused-tests` and `vitest/no-disabled-tests` refuse `.only` and `.skip`) and each workbench, an empty project no chain names. The reader rules every marker and reads the chain behind every workbench. Full collection passes `--staticParse=false` to evaluate runtime titles, setup modules, and shard selection. `--projects` lists only the named projects (an exact name never lists another; a name holding `*` or opening with `!` is a Vitest pattern and may reach beyond the names), exits 64 for a name no project matches without listing any other project, and skips the undiscovered scan. Exit 0 no flag, 3 a flag, 2 tool, listing, or option-table failure, 64 usage.
|
|
17
17
|
- `scripts/titles.ts --base REV [--root DIR] [--json] [--out FILE.json|FILE.txt]` compares the `describe`, `it`, `test`, and `suite` titles of `tests/**/*.test.ts` against `REV`. It flags a title registered fewer times than at `REV` as missing, or as moved when another string literal in `tests/**/*.ts` spells it; the reader rules each moved row by reading its holder. It reports each registration whose title is no literal (dynamic), which the comparison cannot follow, and flags a file that registers fewer of them than at `REV` (lost dynamic). It cannot see a removed `.each` table row or a title registered through an alias such as a `test.extend` result. `--root` defaults to the working directory and may sit below the repository top; `REV` may not open with `-`. Exit 0 no missing or moved title and no lost-dynamic file, 3 any of them, 2 git, filesystem, or lexical refusal, 64 usage.
|
|
18
18
|
- `scripts/measure.ts --rule ID [--options JSON] PATH...` counts one lint rule's hits over the named paths before the rule is enabled. It writes a variant config under `tmp/probes/lint/` that enables only that rule as an error beside the workspace's `plugins` and `jsPlugins` (so a `policy/` rule loads), runs the installed oxlint from the checkout root, and prints the total and the hits per file. A hit is a diagnostic whose code names the rule; another diagnostic, a parse error included, or a linter status other than a clean 0 or 1 refuses the count. `--options` is the rule's JSON options, an array spread after `error` or one value. The variant carries no `ignorePatterns` and no override, so it reads exactly the named paths. It needs `npm ci` first. Exit 0 no hit, 3 a hit, 2 the config or the linter cannot run or reports another diagnostic, 64 usage.
|
|
19
|
+
- `scripts/interleave.ts --plan FILE.json --rounds N [--json] [--out FILE.json|FILE.txt]` compares two commands sample by sample in one run, so a comparison reads a relative change under one host load. The plan is `{ "baseline": SIDE, "candidate": SIDE }`, each side `command` and `args` with an optional `cwd` and `env`; identical sides are a supported A/A comparison. `N` is even and at least 2. `baseline` runs first in each odd round and `candidate` in each even round, each sample a fresh process with no shell. A sample's reading is the number the child prints as its last non-empty standard output line. A sample that cannot start, ends by a signal, exits nonzero, or prints no reading fails the run: the script names the side and the round and prints no report. The report carries each side's samples, median, median absolute deviation, minimum, and maximum, then the difference and the relative change. It rules nothing, so the reader bars the change and reports the host's other load. Exit 0 every sample read, 2 a sample failed or `--out` could not be written, 64 usage.
|
|
19
20
|
|
|
20
|
-
## Select the
|
|
21
|
+
## Select the phases
|
|
21
22
|
|
|
22
|
-
|
|
23
|
+
Run the smallest selection of phases that fully satisfies the request:
|
|
23
24
|
|
|
24
25
|
- **Structural:** centralization, nested-function removal, wrapper cleanup, or test-infrastructure consolidation.
|
|
25
26
|
- **Capability:** research and implement named missing behavior or upstream parity.
|
|
26
|
-
- **Hardening:**
|
|
27
|
+
- **Hardening:** every phase of the complete production-readiness workflow.
|
|
27
28
|
- **Documentation:** a guide, README, or TSDoc pass on one package; it runs step 10 alone.
|
|
28
29
|
|
|
29
30
|
A narrow structural request does not authorize unrelated API redesign. A hardening request does authorize fixing every verified in-scope defect and completing every in-scope deferred capability.
|
|
@@ -32,21 +33,33 @@ Load [research.md](references/research.md) for upstream comparisons, legacy/`old
|
|
|
32
33
|
|
|
33
34
|
Load [contract.md](references/contract.md) whenever the package declares `@orkestrel/contract`, the user requests contract adoption, or local code overlaps validation, parsing, outcomes, safe exception capture, schemas, or contract generation.
|
|
34
35
|
|
|
35
|
-
Load [centralization.md](references/centralization.md) for every structural
|
|
36
|
+
Load [centralization.md](references/centralization.md) for every structural selection and as a mandatory cleanup pass after capability or hardening work.
|
|
36
37
|
|
|
37
|
-
Load [hardening.md](references/hardening.md) for
|
|
38
|
+
Load [hardening.md](references/hardening.md) for a hardening selection, 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
39
|
|
|
39
|
-
Load [document.md](references/document.md) for
|
|
40
|
+
Load [document.md](references/document.md) for a documentation selection and for step 10 of every other selection.
|
|
40
41
|
|
|
41
42
|
Load [bindings.md](references/bindings.md) for a census or a sweep under `.claude/rules/typescript.md` § Bindings, together with [equivalence.md](references/equivalence.md). Before a census item becomes a lint rule, count the rule's hits with `scripts/measure.ts`.
|
|
42
43
|
|
|
43
|
-
Load [equivalence.md](references/equivalence.md) for a structural
|
|
44
|
+
Load [equivalence.md](references/equivalence.md) for a structural selection whose rewrite claims unchanged behavior, and cite it in the claims of the review that judges one.
|
|
45
|
+
|
|
46
|
+
Load [methods.md](references/methods.md) for a capability or hardening selection, and before choosing an instrument or a repair: its selector names the method for each package kind and scenario.
|
|
47
|
+
|
|
48
|
+
## Run a real consumer
|
|
49
|
+
|
|
50
|
+
Before the first review round of a capability or hardening selection, run one real consumer of the composed package end to end, and give its brief:
|
|
51
|
+
|
|
52
|
+
- a real goal the package's consumers have, never the package's own test scenario;
|
|
53
|
+
- the identity of each installed build it runs;
|
|
54
|
+
- one instance reused across the run, because a fresh instance per request hides state carried between requests;
|
|
55
|
+
- the outputs observed, quoted;
|
|
56
|
+
- what the run could not reach.
|
|
44
57
|
|
|
45
58
|
## Execute the workflow
|
|
46
59
|
|
|
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.
|
|
60
|
+
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 and what reopens it in `.orkestrel/<package>/plan.md`, and re-examine every stop at each phase boundary per `.agents/orchestration.md` § Depth, breadth, and machinery. 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
61
|
2. **Map before editing.** Trace public types, implementations, callers, tests, guides, exports, runtime boundaries, installed Orkestrel dependencies, and applicable legacy/upstream references.
|
|
49
|
-
3. **
|
|
62
|
+
3. **Set the claims, the release bar, and the deferral list.** Before the first writer, record them in the tracked `.orkestrel/<package>/plan.md`: 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. Derive the claims from 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. Re-baseline the planned work at each phase boundary per `.agents/orchestration.md`, which owns the step and its boundary with rescoping.
|
|
50
63
|
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
64
|
5. **Implement completely.** Finish every in-scope branch and reuse the exact installed Orkestrel primitives whose semantics match.
|
|
52
65
|
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.
|
|
@@ -56,7 +69,7 @@ Load [equivalence.md](references/equivalence.md) for a structural lane whose rew
|
|
|
56
69
|
10. **Document the final behavior** per [document.md](references/document.md).
|
|
57
70
|
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
71
|
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.
|
|
72
|
+
13. **Review by the size gate, never by the author.** Before the review, run § Run a real consumer. 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
73
|
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
74
|
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.
|
|
62
75
|
|
|
@@ -115,10 +115,8 @@ function describeRun(runner: Runner): string {
|
|
|
115
115
|
}
|
|
116
116
|
|
|
117
117
|
function collectEdits(tokens: readonly Token[]): readonly Edit[] {
|
|
118
|
-
return tokens.
|
|
119
|
-
|
|
120
|
-
token.value === undefined ? log : [...log, { start: token.index, text: token.value }],
|
|
121
|
-
[],
|
|
118
|
+
return tokens.flatMap((token) =>
|
|
119
|
+
token.value === undefined ? [] : [{ start: token.index, text: token.value }],
|
|
122
120
|
)
|
|
123
121
|
}
|
|
124
122
|
```
|
|
@@ -204,10 +202,16 @@ interface Frame {
|
|
|
204
202
|
}
|
|
205
203
|
|
|
206
204
|
function collectEdits(tokens: readonly Token[]): readonly Edit[] {
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
205
|
+
const log: Edit[] = []
|
|
206
|
+
for (const token of tokens) {
|
|
207
|
+
if (log.at(-1)?.start === token.index) continue
|
|
208
|
+
log.push({ start: token.index, text: token.text })
|
|
209
|
+
}
|
|
210
|
+
return log
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
function collectStarts(tokens: readonly Token[]): readonly number[] {
|
|
214
|
+
return collectEdits(tokens).map((edit) => edit.start)
|
|
211
215
|
}
|
|
212
216
|
|
|
213
217
|
function stepStack(stack: readonly Frame[], indent: number, key: string): readonly Frame[] {
|
|
@@ -344,10 +348,12 @@ Clear fixture, `logs.last.clear.ts`:
|
|
|
344
348
|
|
|
345
349
|
```ts
|
|
346
350
|
function collectEdits(tokens: readonly Token[]): readonly Edit[] {
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
+
const log: Edit[] = []
|
|
352
|
+
for (const token of tokens) {
|
|
353
|
+
if (log.at(-1)?.start === token.index) continue
|
|
354
|
+
log.push({ name: token.name, start: token.index })
|
|
355
|
+
}
|
|
356
|
+
return log
|
|
351
357
|
}
|
|
352
358
|
|
|
353
359
|
function declares(tokens: readonly Token[], name: string): boolean {
|