@orkestrel/scaffold 0.0.122 → 0.0.124
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +539 -0
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1163 -0
- package/dist/bin/main.js +21 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +13 -7
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -3
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -2
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -2
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +16 -3
- 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 +1 -1
- 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 +14 -13
- package/dist/host/agents/skills/orkestrel-parallel/references/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 +2 -1
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +18 -1
- package/dist/host/claude/AGENTS.md +1 -1
- 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 +2 -2
- package/dist/host/claude/agents/orkestrel.md +30 -30
- package/dist/host/claude/agents/reviewer.md +2 -2
- package/dist/host/claude/agents/scout.md +2 -1
- package/dist/host/claude/agents/verifier.md +1 -1
- package/dist/host/claude/rules/campaign.md +12 -11
- package/dist/host/claude/rules/documentation.md +1 -0
- 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 +4 -0
- package/dist/host/claude/rules/writing.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +4 -1
- 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 +3 -3
- package/dist/host/codex/agents/reviewer.toml +6 -2
- package/dist/host/codex/agents/scout.toml +5 -1
- package/dist/host/codex/agents/verifier.toml +6 -1
- package/dist/host/guides/agent.md +1119 -457
- package/dist/host/guides/contract.md +226 -104
- package/dist/host/guides/database.md +12 -12
- package/dist/host/guides/ndjson.md +94 -21
- package/dist/host/guides/ollama.md +22 -18
- package/dist/host/guides/probe.md +29 -27
- package/dist/host/guides/reason.md +377 -114
- package/dist/host/guides/scaffold.md +43 -21
- package/dist/host/guides/study.md +538 -450
- package/dist/host/guides/tool.md +163 -58
- package/dist/host/manifest.json +70 -52
- package/dist/src/core/index.cjs +21 -20
- 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 +21 -20
- 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 +15 -15
|
@@ -38,7 +38,7 @@ 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 |
|
|
@@ -46,6 +46,8 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
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
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.
|
|
49
51
|
- `planner` also carries the read-only consultation § Engines admits for Claude Fable 5.1, on the engine the dispatch names.
|
|
50
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.
|
|
51
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.
|
|
@@ -57,6 +59,7 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
57
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.
|
|
58
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.
|
|
59
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.
|
|
60
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.
|
|
61
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.
|
|
62
65
|
- Record mechanical source adoption as Orchestrator integration or a writer unit. Reserve the runner name for a verifier that made no source repair.
|
|
@@ -103,12 +106,14 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
103
106
|
|
|
104
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.
|
|
105
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.
|
|
106
111
|
- When a failure recurs, read the exact input and output of the failing case before adding capability, and fix the cause.
|
|
107
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.
|
|
108
113
|
- Prove a change in one consumer, with its gate green, before spreading it to the rest.
|
|
109
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.
|
|
110
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.
|
|
111
|
-
- 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.
|
|
112
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.
|
|
113
118
|
- Ship the proven fix first, and run experiments behind it under a stated cap.
|
|
114
119
|
|
|
@@ -127,7 +132,7 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
127
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.
|
|
128
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.
|
|
129
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.
|
|
130
|
-
- 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.
|
|
131
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.
|
|
132
137
|
- An all-confirmed round ends the audit. A round needs an added or repaired claim to test; reviewer appetite is not a subject.
|
|
133
138
|
|
|
@@ -135,9 +140,9 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
135
140
|
|
|
136
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.
|
|
137
142
|
|
|
138
|
-
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.
|
|
139
|
-
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.
|
|
140
|
-
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.
|
|
141
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.
|
|
142
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.
|
|
143
148
|
6. **Verify.** `verifier` runs the tree-wide gates once.
|
|
@@ -162,7 +167,8 @@ A large change opens with a concise goal and its exit criterion, short enough to
|
|
|
162
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.
|
|
163
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.
|
|
164
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.
|
|
165
|
-
- 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.
|
|
166
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.
|
|
167
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.
|
|
168
174
|
- No role, the Orchestrator included, reads, prints, copies, uploads, or packages a secret: `.env*`, `.npmrc`, `auth.json`, keys, tokens, `CURSOR_API_KEY`.
|
|
@@ -26,12 +26,13 @@ description: >-
|
|
|
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
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. 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.
|
|
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.
|
|
@@ -28,7 +28,7 @@ Apply these rules to every command that outlives the turn that starts it: a benc
|
|
|
28
28
|
|
|
29
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`.
|
|
30
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.
|
|
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.
|
|
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.
|
|
32
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.
|
|
33
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.
|
|
34
34
|
|
|
@@ -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,7 @@ 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
|
-
- Supply each receipt a claim needs (the command, its input identity, and its exit)
|
|
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
22
|
- Keep the verdict shape `SKILL.md` § Verdict shape fixes; replace it only when a skill the dispatch names fixes another.
|
|
23
23
|
|
|
24
24
|
## The successor brief
|
|
@@ -16,6 +16,7 @@ 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
21
|
## Select the phases
|
|
21
22
|
|
|
@@ -42,11 +43,23 @@ Load [bindings.md](references/bindings.md) for a census or a sweep under `.claud
|
|
|
42
43
|
|
|
43
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.
|
|
44
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.
|
|
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 selection whos
|
|
|
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 {
|
|
@@ -14,6 +14,7 @@ This reference governs the guide pass for one package, `AGENTS.md` § Work loop
|
|
|
14
14
|
2. **README.** Set the pitch equal to the guide's tagline; keep the install and link lines in step with the shipped exports.
|
|
15
15
|
3. **TSDoc.** Give each export the change touched the block `.claude/rules/typescript.md` § Comments and API documentation fixes, with fictional descriptive data in its `@example`.
|
|
16
16
|
4. **Fences.** Import through the published specifier and run each example; read what it returns before writing the comment beside it.
|
|
17
|
+
5. **Ergonomics.** Where the guide claims authoring ergonomics, pair the executed example with an independent reader who receives only the authored declaration, and test that reader's interpretation.
|
|
17
18
|
|
|
18
19
|
## Choose the rewrite direction
|
|
19
20
|
|
|
@@ -8,7 +8,8 @@ with a row for each class this contract names that the changed code admits.
|
|
|
8
8
|
|
|
9
9
|
## Hold the contract
|
|
10
10
|
|
|
11
|
-
- When a rewrite changes traversal, membership, allocation, or materialization, compare its cost growth with the baseline on the package's realistic load and rule the measured effect under `.claude/rules/quality.md` § Performance.
|
|
11
|
+
- When a rewrite changes traversal, membership, allocation, or materialization, compare its cost growth with the baseline on the package's realistic load and rule the measured effect under `.claude/rules/quality.md` § Performance. When a profile places the rewritten function on a hot path, also read its constant factor against the baseline, and rule that reading under the same section.
|
|
12
|
+
- When a loop that a profile places on a hot path recomputes a result for an input it already computed within one operation, a memo under `.claude/rules/typescript.md` § Bindings **Exemptions** can hold the result, and so can `#` fields of an entity created for the call under **Per-call state** when the call's awaits or callbacks change that state. Rule the gain under `.claude/rules/quality.md` § Performance, and keep every element read and effect this contract matches.
|
|
12
13
|
- Treat every value the declared parameter types admit as inside the contract: holes, entries read
|
|
13
14
|
through getters (their count and order), entries that throw, an array whose `Symbol.iterator` is
|
|
14
15
|
missing or replaced, and an iterator's `return()`.
|
|
@@ -40,7 +40,7 @@ protocol tests prove the protocol, and only a real client of that class proves t
|
|
|
40
40
|
integration. Drive it end to end, record the exact commands, and record what that client
|
|
41
41
|
could NOT reach as an honest limit rather than an untested assumption.
|
|
42
42
|
|
|
43
|
-
|
|
43
|
+
`AGENTS.md` § Non-negotiable rules owns the law on mocks, fakes, and fake clocks. Use recorders for callbacks and customizable data factories/stubs for inert shapes.
|
|
44
44
|
|
|
45
45
|
## Design live-service tests
|
|
46
46
|
|