@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.
Files changed (85) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +57 -9
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
  3. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +539 -0
  4. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1163 -0
  5. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
  6. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
  7. package/dist/bin/main.js +8 -6
  8. package/dist/bin/main.js.map +1 -1
  9. package/dist/host/agents/orchestration.md +29 -18
  10. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +7 -6
  11. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +3 -2
  12. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
  13. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
  14. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -2
  15. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +3 -2
  16. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +24 -11
  17. package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +18 -12
  18. package/dist/host/agents/skills/orkestrel-harden/references/document.md +1 -0
  19. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +2 -1
  20. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +4 -4
  21. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +642 -0
  22. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +665 -0
  23. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +16 -15
  24. package/dist/host/agents/skills/orkestrel-parallel/references/{claude.md → claude-code.md} +13 -13
  25. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
  26. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1433 -0
  27. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +12 -9
  28. package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
  29. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +39 -8
  30. package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
  31. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
  32. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
  33. package/dist/host/claude/AGENTS.md +2 -2
  34. package/dist/host/claude/agents/analyst.md +1 -1
  35. package/dist/host/claude/agents/builder.md +1 -1
  36. package/dist/host/claude/agents/distiller.md +2 -1
  37. package/dist/host/claude/agents/grok.md +2 -2
  38. package/dist/host/claude/agents/opus.md +8 -7
  39. package/dist/host/claude/agents/orkestrel.md +7 -7
  40. package/dist/host/claude/agents/planner.md +3 -3
  41. package/dist/host/claude/agents/reviewer.md +3 -3
  42. package/dist/host/claude/agents/scout.md +2 -1
  43. package/dist/host/claude/agents/verifier.md +2 -2
  44. package/dist/host/claude/rules/campaign.md +15 -13
  45. package/dist/host/claude/rules/documentation.md +1 -0
  46. package/dist/host/claude/rules/names.md +13 -7
  47. package/dist/host/claude/rules/patterns.md +14 -0
  48. package/dist/host/claude/rules/quality.md +4 -1
  49. package/dist/host/claude/rules/tests.md +5 -1
  50. package/dist/host/claude/rules/workspace.md +9 -0
  51. package/dist/host/claude/rules/writing.md +1 -1
  52. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  53. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  54. package/dist/host/codex/agents/analyst.toml +6 -6
  55. package/dist/host/codex/agents/astra.toml +1 -1
  56. package/dist/host/codex/agents/builder.toml +1 -1
  57. package/dist/host/codex/agents/distiller.toml +4 -2
  58. package/dist/host/codex/agents/grok.toml +5 -2
  59. package/dist/host/codex/agents/opus.toml +6 -4
  60. package/dist/host/codex/agents/planner.toml +6 -5
  61. package/dist/host/codex/agents/reviewer.toml +9 -8
  62. package/dist/host/codex/agents/scout.toml +5 -1
  63. package/dist/host/codex/agents/verifier.toml +8 -3
  64. package/dist/host/dotfiles/gitignore +1 -2
  65. package/dist/host/guides/agent.md +1119 -457
  66. package/dist/host/guides/ndjson.md +81 -21
  67. package/dist/host/guides/ollama.md +22 -18
  68. package/dist/host/guides/probe.md +29 -27
  69. package/dist/host/guides/scaffold.md +42 -15
  70. package/dist/host/guides/study.md +538 -450
  71. package/dist/host/manifest.json +81 -63
  72. package/dist/host/tests/config.test.ts +7 -0
  73. package/dist/src/core/index.cjs +14 -8
  74. package/dist/src/core/index.cjs.map +1 -1
  75. package/dist/src/core/index.d.cts +1 -4
  76. package/dist/src/core/index.d.ts +1 -4
  77. package/dist/src/core/index.js +14 -8
  78. package/dist/src/core/index.js.map +1 -1
  79. package/dist/src/server/index.cjs +87 -8
  80. package/dist/src/server/index.cjs.map +1 -1
  81. package/dist/src/server/index.d.cts +50 -6
  82. package/dist/src/server/index.d.ts +50 -6
  83. package/dist/src/server/index.js +87 -10
  84. package/dist/src/server/index.js.map +1 -1
  85. package/package.json +2 -2
@@ -1,18 +1,18 @@
1
1
  ---
2
2
  name: reviewer
3
- description: 'Opus 5.5 review lane over implemented work, read-only: design fit, API and vocabulary, architecture shape, guide voice by default; correctness, constraints, and test sufficiency when the dispatch assigns the objective lane. Tests numbered claims and returns the falsify verdict. Never edits.'
3
+ description: 'Opus 5.5 review lane by default, on another engine when the dispatch names one, over implemented work, read-only on source: design fit, API and vocabulary, architecture shape, guide voice by default; correctness, constraints, and test sufficiency when the dispatch assigns the objective lane. Tests numbered claims and returns the falsify verdict. Never edits source.'
4
4
  tools: Read, Grep, Glob
5
5
  model: opus
6
6
  effort: high
7
7
  permissionMode: dontAsk
8
8
  ---
9
9
 
10
- On Claude Opus 5.5, you review by trying to falsify the claims. You hold no edit tool and run no command; your final message is the verdict.
10
+ On Claude Opus 5.5 by default, or on the engine the dispatch names, you review by trying to falsify the claims. You edit no source; your final message is the verdict. Where the dispatch names a probe folder and your tools include a shell, write throwaway probes only in that folder, run them under `.agents/skills/orkestrel-parallel/SKILL.md` § Bound the host, and delete the folder before returning. Otherwise take the receipts the dispatch supplies, and run no mutating command.
11
11
 
12
12
  ## Do
13
13
 
14
14
  1. Read the claims file, the actual diff and `git status --porcelain` the dispatch supplies, `AGENTS.md`, the rules whose `paths` match the changed files, the guide, and enough surrounding source to judge. The diff and `git status` are required only for a code subject; return a deviation if that diff is missing.
15
- 2. Hold the lane the dispatch names and say which one. Subjective: the requested shape and voice are present, names and boundaries are coherent, the work sits at the right layer, each concept earns its place, the guide matches the code. Objective: correctness under adverse orderings, what the contracts and installed declarations permit, dependency and range truth, the missing seam or the assertion that cannot fail, the letter of the rules.
15
+ 2. Hold the lane the dispatch names and say which one, under the lens `.agents/orchestration.md` § Roles gives that lane.
16
16
  3. Try to falsify each claim with a concrete input, state, or interleaving. Before confirming a claim about a proof, name the mutation that would make the proof fail and whether the assertions distinguish it.
17
17
  4. Rule a claim whose only evidence is the writer's report `UNRESOLVED`. Cite a capture for every claim about a rendered surface; mark what the portfolio cannot show `NOT-EVIDENCED`.
18
18
  5. Refer a question outside your lane to the other lane or the Orchestrator with its evidence; never rule on it.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: scout
3
- description: 'Haiku 5.5 read-only exact bounded lookup of files, symbols, and seams. Returns file:line pointers and a shape summary. Refuses broad mapping, context absorption, and exploratory or fishing reads. Never edits or judges quality.'
3
+ description: 'Haiku 5.5 read-only exact bounded lookup of files, symbols, and seams, and row-by-row marking of a list a search made against explicit criteria. Returns file:line pointers and a shape summary. Refuses broad mapping, context absorption, and exploratory or fishing reads. Never edits or judges quality.'
4
4
  tools: Read, Grep, Glob
5
5
  model: haiku
6
6
  effort: low
@@ -17,6 +17,7 @@ distillation, and exploratory or fishing reads; refer the dispatch to `.agents/o
17
17
  1. Take one bounded question: what to find and where to stop.
18
18
  2. Read the map the dispatch supplies (the Orchestrator runs the `orkestrel-scout` skill's `map.ts` and names its path); then search by name, symbol, export, and call site for what the map leaves open. Open a file only far enough to confirm a match. Refuse a dispatch that names no map and asks for one.
19
19
  3. Return every hit as `file:line` with a one-line shape note, grouped by the question's parts, and name the search patterns and roots you used so the coverage is checkable.
20
+ 4. When the dispatch supplies a listed population and explicit criteria, mark every listed row against those criteria and return each row with its mark, and leave a row the criteria do not decide unmarked with its reason. Add no row by hand.
20
21
 
21
22
  ## Return
22
23
 
@@ -13,7 +13,7 @@ On Claude Haiku 5.5, run the requested gates and report their results. Write onl
13
13
  ## Do
14
14
 
15
15
  1. Run exactly the commands the dispatch names, in order. Default scoped sweep: the format check and lint over the changed files, then the `check:` script and `test:` script of each project the dispatch names. Default tree-wide sweep, only when the dispatch says tree-wide: `npm run format:check`, `npm run lint:check`, `npm run check`, `npm run build`, `npm test`.
16
- 2. Read each gate bare. Never pipe it through `tail` or `grep`.
16
+ 2. Read each gate bare. Never pipe it through `tail` or `grep`. When the shell yields before a command exits, keep its output in its file and resume per `.agents/skills/orkestrel-parallel/SKILL.md` § Run evidence commands until its terminal record arrives, and send no final message before every named gate has returned. When a dispatch hands you a log the Orchestrator ran, read it whole and confirm its command, its source identity, its output, and its exit; that read is the independent receipt, and you report it as a read.
17
17
  3. Record each gate's outcome by exit code. A gate that "mostly passes" failed.
18
18
  4. On failure, capture the exact failing excerpt and the `file:line` it points to.
19
19
  5. Report a failure that passes alone per `orkestrel-dispatch` § Write the brief, and rerun nothing to reclassify it; run again only after a changed condition or an explicit investigation request.
@@ -22,7 +22,7 @@ On Claude Haiku 5.5, run the requested gates and report their results. Write onl
22
22
 
23
23
  - A source-mutating gate (`lint`, `format`, or any `--fix`), and a build without the declarations and holds `.agents/orchestration.md` § Permission floor requires.
24
24
  - `git checkout`, `git restore`, `git stash`, `git reset`, `git clean`. Read a dirty tree as the expected state.
25
- - Any command that installs, commits, pushes, publishes, deletes beyond what § Permission floor permits, or reads a secret (`.env*`, `.npmrc`, `auth.json`, keys, tokens), whatever the dispatch says.
25
+ - Any command that installs, commits, pushes, publishes, deletes beyond what § Permission floor permits, or reads a secret `.agents/orchestration.md` § Permission floor names, whatever the dispatch says.
26
26
 
27
27
  ## Return
28
28
 
@@ -19,34 +19,36 @@ paths:
19
19
 
20
20
  A package directory holds:
21
21
 
22
- | File | Holds | When |
23
- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
24
- | `plan.md` | a concise goal and exit criterion that serve as a goal prompt, each repository the campaign changes by name and URL, § State, open decisions, deferred triggers, § Sequence | always |
25
- | `ledger.md` | one row per dispatched unit and per user ruling on routing or scope: date, unit, role, carrier | always |
26
- | `README.md` | the file map, the read order, and the id law | when the folder holds more than `plan.md` and `ledger.md` |
27
- | `tenets.md` | the campaign's standing directives | when the campaign has any |
28
- | `ideas.md`, `gaps.md` | ideas set aside and library gaps, each numbered for life with its reason and its reopen trigger | when the campaign records any |
29
- | `designs/`, `research/` | one design or research record per subject | when a chunk needs one |
30
- | a verdict file | the verdict of an open seam | until the seam closes |
22
+ | File | Holds | When |
23
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
24
+ | `plan.md` | a concise goal and exit criterion that serve as a goal prompt, each repository the campaign changes by name and URL, the governing skills, § State, open decisions, deferred triggers, § Sequence | always |
25
+ | `ledger.md` | one row per dispatched unit and per user ruling on routing or scope: date, unit, role, carrier | always |
26
+ | `README.md` | the file map, the read order, and the id law | when the folder holds more than `plan.md` and `ledger.md` |
27
+ | `tenets.md` | the campaign's standing directives | when the campaign has any |
28
+ | `ideas.md`, `gaps.md` | ideas set aside and library gaps, each numbered for life with its reason and its reopen trigger | when the campaign records any |
29
+ | `designs/`, `research/` | one design or research record per subject | when a chunk needs one |
30
+ | a verdict file | the verdict of an open seam | until the seam closes |
31
31
 
32
32
  - Write a file about one package under that package's directory, and a file about two or more packages at the top level.
33
- - Fill a ledger row's role cell with a name from `.agents/orchestration.md` § Roles, `user`, or `Orchestrator`. Write no row for the Orchestrator's own commit.
33
+ - Fill a ledger row's role cell with a name from `.agents/orchestration.md` § Roles and the engine that role ran on, `user`, or `Orchestrator`. Write no row for the Orchestrator's own commit.
34
34
 
35
35
  ## Content
36
36
 
37
37
  - Track every file under `.orkestrel/`. Cite a tracked file, a commit, or a published URL. Cite no git-ignored path, no agent memory, and no path outside the repository; name a sibling repository by its package name and a path inside it.
38
- - Name no harness, model, provider, harness tool, operating system, shell, or machine as the host or engine of the work. Name a lane by its role. A product statement about a host family follows `.claude/rules/portability.md` § Claims.
38
+ - Name no harness, model, provider, harness tool, operating system, shell, or machine as the host or engine of the work, except the engine in a ledger row's role cell per § Layout. Name a lane by its role. A product statement about a host family follows `.claude/rules/portability.md` § Claims.
39
39
  - Write every line as a directive, a fact, or a table cell, per `.claude/rules/writing.md` § Instruction files: absolute dates, one home per fact, a tree location by symbol and file. A decision or a measurement lives in the commit that made it; cite the commit.
40
- - `plan.md` holds a harden campaign's claims, its release bar, and its deferral list, each deferred item with its trigger and its owner.
40
+ - `plan.md` holds the campaign's claims, its release bar, each seam's stop with what reopens it, and its deferral list, each deferred item with its trigger and its owner.
41
+ - Name in `plan.md` the skill that governs each kind of unit the campaign dispatches, whatever the campaign's own name: `orkestrel-harden` for hardening a package.
41
42
  - Keep live state out: engine availability, session ownership, process ids, installed versions, and another repository's state live in the roster, `package.json`, and that repository.
42
43
  - Keep unit briefs, reports, journals, and drafts under the checkout's `tmp/` (`.agents/orchestration.md` § tmp layout); that file's § Cleanup owns what a unit's files carry before they go.
43
44
  - Record a prepared, unapplied change as text in `plan.md` or as a commit, never as a pointer to scratch.
44
45
 
45
46
  ## Start a session
46
47
 
47
- 1. Read the package folder's `README.md` when present, then `plan.md` § State, then the first open chunk of § Sequence.
48
+ 1. Read the package folder's `README.md` when present, then `plan.md` § State, then each skill the plan names as governing the first open chunk of § Sequence, then that chunk.
48
49
  2. Run `git status --porcelain -b`, `git log @{upstream}..`, and `node .agents/skills/orkestrel-dispatch/scripts/sweep.ts --report`. Reconcile each difference with `plan.md` § State before you act.
49
50
  3. Act only on what the folder, the tree, and git hold. Agent memory from another machine or harness is absent.
51
+ 4. When a campaign opens, list each `ROADMAP.md` item whose reopen trigger the campaign meets, and plan it or rule it out in `plan.md`.
50
52
 
51
53
  ## Hand off and close
52
54
 
@@ -83,6 +83,7 @@ A skill, a tool description, and a refusal message each teach an agent mid-task.
83
83
 
84
84
  - Put the critical path in the tool description, most important first: a worked example, the key nesting, and the reply shape. A harness abbreviates a nested schema and delivers the description intact; never leave the teaching to the schema.
85
85
  - Make every refusal orient, name, or correct: state the subject, the exact key path, the expected shape, the valid candidates, and every missing and every unexpected item, in one refusal.
86
+ - Keep the provenance a refusal computed, its token, span, reason, and known field, and never invent the value or field the caller intended.
86
87
  - Refuse with the correction in the message. Never coerce a malformed input and never silently drop it. Encode an untrusted identifier in a diagnostic, JSON-encoded and length-capped, so malformed input cannot fake or balloon the message.
87
88
  - Acknowledge or state, never both: a mutation returns an acknowledgement and a read returns state. Say the split in both tools' descriptions so neither is polled for the other's job.
88
89
 
@@ -217,13 +217,19 @@ For `_` bindings:
217
217
 
218
218
  ## Files and folders
219
219
 
220
- | Kind | Pattern |
221
- | --------------- | -------------------------------------------------------------------------------- |
222
- | Domain folder | lowercase plural entity: `agents/`, `tools/` |
223
- | Implementation | PascalCase entity: `Agent.ts` |
224
- | Function module | camelCase function: `renderGrid.ts` |
225
- | Test | source filename without extension + `.test`: `Agent.test.ts`, `useTheme.test.ts` |
226
- | Guide | lowercase domain: `agents.md` |
220
+ | Kind | Pattern |
221
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
222
+ | Domain folder | lowercase plural entity: `agents/`, `tools/` |
223
+ | Implementation | PascalCase entity: `Agent.ts` |
224
+ | Function module | camelCase function: `renderGrid.ts` |
225
+ | Test | source filename without extension + `.test`: `Agent.test.ts`, `useTheme.test.ts` |
226
+ | Guide | lowercase domain: `agents.md` |
227
+ | JSON file | one lowercase word, with a lowercase dotted qualifier where a tool reads the stem: `host.json`, `tsconfig.core.json` |
228
+ | Fixture | one lowercase word, else camelCase: `sourceManifest.txt` |
229
+ | Other file | one lowercase word naming its subject in its folder, with a lowercase dotted qualifier where a tool reads the stem: `deps.sh`, `vite.journey.config.ts` |
230
+
231
+ - When you name a tracked file or folder, write no hyphen and use the form the preceding table fixes for its kind. A hyphen stands only where an external convention fixes the name, such as a skill directory under `.claude/rules/documentation.md` § Workflow skills or `package-lock.json`. A file a tool generates under a name the tool fixes, a vendored mirror's fetched name, and every path under `tmp/` are exempt.
232
+ - When a path sits under a folder whose name opens with a dot, such as `.agents/`, `.claude/`, `.codex/`, or `.cursor/`, the preceding bullet does not bind it: a harness can read a file there by its name, so name it for that harness. Claude Code loads a lowercase `claude.md` as memory wherever it sits, so the Claude transport is `.agents/transports/claude-cli.md`.
227
233
 
228
234
  ## Fixed lifecycle vocabulary
229
235
 
@@ -129,6 +129,20 @@ Use these orthogonal contract mechanisms:
129
129
  - every parsed result satisfies its guard.
130
130
  - Derive parser and guard from one source or test the round trip.
131
131
 
132
+ ### Admission and refusal
133
+
134
+ - Choose a hand guard or a shape-derived guard by how often the check runs and the representation it reads: a hand guard with a directional parity test on a per-element path, a derived guard at a once-per-entity door, and a diagnostic computed only after a refusal.
135
+ - Admit an owned record from its raw form before any projection or fallback, so that corrupt-present stays apart from absent.
136
+ - State shape soundness, lossless semantic admission, and authoring validity as separate claims, and prove each at its own door.
137
+ - Treat persistence canonicalization as part of the declared identity round trip: when a store reorders or rewrites a value, compare identity by the value the declaration states.
138
+ - Make a refusal bound cover the ownership and capture work paid before validation: read the limit during capture, with one counter per door call.
139
+ - Report unread or unavailable evidence as unread, never as a false predicate or an empty success.
140
+ - Bind admission and approval to the exact operation and instance, and recheck that binding across every suspension and callback before dispatch.
141
+ - Name the actual commit boundary in a restore or continuation claim, partial commits included.
142
+ - Declare a parser's whole admitted language and its adjacent refusals, and prove them with a table of the class; never tune the parser example by example.
143
+ - Derive a decision from validated inputs; an editable prior result never substitutes for them.
144
+ - Project a value outward by its authorship and trust origin, and accept no authority channel from a client.
145
+
132
146
  ### Foreign contracts
133
147
 
134
148
  A value returned by an interface another package publishes is FOREIGN data. Own it, validate what you dereference, and narrow nothing.
@@ -33,7 +33,7 @@ These rules govern how a claim is established: the evidence read before a change
33
33
 
34
34
  ## Instruments
35
35
 
36
- - An instrument counts as evidence only after it has failed: pair every probe, comparison, or matrix with a negative control that must fail under the same conditions, drawn from outside the population the instrument covers.
36
+ - An instrument counts as evidence only after it has failed: pair every probe, comparison, or matrix with a negative control that must fail under the same conditions, drawn from outside the population the instrument covers and inside the domain the claim promises. A control that leaves that domain proves nothing about the instrument; prove that behavior under its own claim.
37
37
  - When a TypeScript question can name a workspace project, a case (files plus a test), and a control (files, test, the stage it must fail at, and why), call the `prove` tool the `probe` MCP server registers. Quote its closing line (`receipt probe:<digest>:…` or `no receipt`) where the claim is reported. A `no receipt` line leaves the claim unproved; report the stage that refused.
38
38
  - When the question supplies no project, no case, or no control, write a probe per `.claude/rules/tests.md` § Probes and report the probe's control and coverage.
39
39
  - When no `probe` server is registered, register one outside the repository in the harness's user or local MCP scope, pointing at `node_modules/@orkestrel/probe/dist/bin/main.js`, and start it in the repository whose projects the question names. A scaffold target holds no `.mcp.json`.
@@ -57,6 +57,9 @@ These rules govern how a claim is established: the evidence read before a change
57
57
  - Before the run, size the fixtures, the sample count, and the threshold to the case, and state the reasoning and the result that makes the change worth keeping.
58
58
  - Read the difference between methods against each side's reported uncertainty, and record no difference smaller than the result stated before the run.
59
59
  - Report every measurement with the host's other load during the run.
60
+ - Compare two builds interleaved in one run under one host load, with `.agents/skills/orkestrel-harden/scripts/interleave.ts`. Read a published side from the published artifact, calibrate the run with identical sides, and bar the relative change, never an absolute reading from another moment.
61
+ - Price a cost over the caller's whole lifecycle and workload: construction, restoration, transfer, and decision beside the warm saving.
62
+ - Derive a cost stop from what the consumer spends around the cost, and state responsiveness and throughput as separate claims.
60
63
  - Rule a cost finding advisory unless it shows its effect under a realistic load, and never carry an advisory into a fix brief as a required change; `.agents/skills/orkestrel-falsify/SKILL.md` § Verdict shape places it in a review lane's return.
61
64
 
62
65
  ## Ecosystem reuse
@@ -42,7 +42,7 @@ These rules govern what a test asserts and where it lives, the cross-cutting and
42
42
  - Test observable behavior, not implementation details.
43
43
  - Assert the membership a discovered or globbed set must have, not a total that a partly empty population satisfies. A glob spanning two locations passes a size check while one of them matches nothing.
44
44
  - Never assert an implementation against itself. Compare the answer to a declaration, a fixture, or a second mechanism that could disagree with it. Re-deriving the answer the same way the source derives it produces a test that passes for every value the source ever returns, and it reads exactly like a real one.
45
- - Probe a host-varying property at runtime, on the host the test is running on, and assert against what the probe returned. Filesystem case folding, path separators, permission bits, and rename semantics differ per host, so a fixture built on one host describes that host and silently measures something else on the next.
45
+ - Probe a host-varying property at runtime, on the host the test is running on, and assert against what the probe returned. Filesystem case folding, path separators, permission bits, and rename semantics differ per host, and a thrown error's class or message differs per Node major, so a fixture built on one host describes that host and silently measures something else on the next.
46
46
  - Assert a runtime-chosen result as the property it must have, not as the number one run produced. Compression, timing, and buffer sizing are the runtime's choice, so pin the relationship the test depends on — that the encoded form is larger, that the second call is faster — and let the assertion fail when the input drifts out of the range where that relationship holds.
47
47
  - Measure an elapsed interval with `performance.now()`, never `Date.now()`. `Date.now()` returns whole milliseconds, so an interval built from two of its readings truncates at both ends and can under-report by a millisecond — enough to fail a boundary assertion against a timer that behaved correctly. `performance.now()` is monotonic and sub-millisecond, and it does not move when the wall clock does.
48
48
  - Give a conditional skip the mechanism that makes it inapplicable, cited, not the platform name alone. A test skipped on a platform is a test nobody re-examines; a test skipped because a named API rejects a named case is one anybody can re-check.
@@ -51,6 +51,8 @@ These rules govern what a test asserts and where it lives, the cross-cutting and
51
51
  - A browser case restores every runner global it changes before it ends.
52
52
  - A proof that runs before `build` in the gate chain resolves no `dist/` path; a proof that deliberately consumes the built entry loads it at run time through a resolved path and refuses a stale build.
53
53
  - When data a generator renders gains a new shape, the generator's test gains that shape before the data ships.
54
+ - Give a negative control on a synchronous guard a bounded fixture that finishes with the guard removed and whose count differs, because a test timer on the same thread cannot interrupt it.
55
+ - Prove a consumer migration past what compiles: cover the defaulted branches that still compile and the entries outside the check graph.
54
56
  - The revert that proves a repair reddens exactly the test that names the defect. Keep the import and collection graph valid while reverting, and confirm the named test was collected. A revert that reddens anything beyond that test broke the harness, and its count is not evidence.
55
57
  - Use `it.todo()` only for explicitly out-of-scope roadmap work, never to complete the current request. Every conditional skip has a narrow verifiable applicability reason. Never commit `.only` or `.skip`; `vitest/no-focused-tests` and `vitest/no-disabled-tests` refuse both.
56
58
  - Do not create test files solely for `constants.ts`, barrels, error definitions, or `types.ts`.
@@ -174,6 +176,8 @@ A test that spawns a process, packs, installs, or drives a real build is a proof
174
176
  path, run its `distribution` project before accepting the change.
175
177
  - Put a study's proofs under `tests/studies/` in the `studies` project, which
176
178
  `.claude/rules/workspace.md` § Test project matrix places.
179
+ - Keep a study's developmental selection and its untouched confirmation as separate evidence
180
+ populations, and withhold expected outputs and population membership from the run.
177
181
  - Put in `studies` only the proofs the `@orkestrel/study` engine drives. Place a slow end-to-end proof of
178
182
  the package's own features that no study engine drives, such as its built executable run against
179
183
  a fixture workspace, as an integration test under § Cross-cutting proofs. Place it by the scope it
@@ -42,6 +42,11 @@ Use only the environments a project needs, and keep the root dependency model in
42
42
  found at the same name.
43
43
  - `package.json`'s `bin` key is the installed command name. The entry path is the value and does
44
44
  not carry that name.
45
+ - Keep every ignored output at the workspace root or under `tmp/`, and write no `.gitignore`
46
+ pattern that reaches into a nested tracked folder. A path under a dot folder, such as
47
+ `.claude/worktrees/`, is exempt. When a tool writes its output inside a tracked folder by
48
+ default, point the tool's own setting at a directory under `tmp/`. A bare name or glob that
49
+ names a root-level tool output, such as `dist`, `tmp`, or `*.log`, is a root ignore.
45
50
 
46
51
  ## Aliases
47
52
 
@@ -166,6 +171,10 @@ environment axis is one project per src/app axis × environment, plus one per ex
166
171
  - Give every browser project `test.browser.commands` from `configs/commands.ts`: each root factory
167
172
  that names the Playwright provider reads the record, and a project that spreads another
168
173
  factory's `test.browser`, as `appVue` and every `journey:<variant>` project do, keeps it.
174
+ - Give every browser project `test.browser.screenshotDirectory` from the one `screenshots`
175
+ binding the root configuration declares beside `browserOptions`, which resolves
176
+ `tmp/captures/screenshots` from the workspace root; each root factory that names the Playwright
177
+ provider reads it, and a project that spreads another factory's `test.browser` keeps it.
169
178
 
170
179
  The workspace-proof axis is cross-cutting. Each proof covers the whole workspace rather than
171
180
  one environment, so each is its own project:
@@ -56,7 +56,7 @@
56
56
  - Cut every clause that persuades, reassures, or explains to a person.
57
57
  - Give a rule one home. Point at it from elsewhere; never restate it.
58
58
  - When a rule requires a check against a declared type or shape, state the standard at which the check stops.
59
- - Keep an example only when it disambiguates the rule.
59
+ - Keep an example only when it disambiguates the rule. `.agents/skills/orkestrel-harden/references/methods.md` keeps one reading and one example per method.
60
60
  - When an instruction file or a brief governs a quantity, state the property the quantity must serve and leave the figure to the case: never fix a fixture size, a sample count, a percentage, or a threshold, and describe a fixture by its kind and the load it represents. Keep a figure only where it is a contract: a limit a protocol, format, standard, or external tool fixes, an exit code, a measurement with its run, a version, a date, or a cardinality a design law fixes (one word per name, one writer per checkout).
61
61
  - Keep `AGENTS.md` to the laws every task needs and the always-loaded set small: move a procedure into a skill and scope a rule with `paths`.
62
62
 
@@ -5,6 +5,6 @@ description: Research, audit, refactor, implement, centralize, test, document, a
5
5
 
6
6
  # Load the canonical workflow
7
7
 
8
- Read `.agents/skills/orkestrel-harden/SKILL.md` completely, then read every reference it requires for the selected work lane. Follow that canonical workflow before acting.
8
+ Read `.agents/skills/orkestrel-harden/SKILL.md` completely, then read every reference it requires for the selected phases. Follow that canonical workflow before acting.
9
9
 
10
10
  Apply `AGENTS.md` § Authority and loading.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: orkestrel-parallel
3
3
  description: >-
4
- Run parallel work: lanes inside one session (subagents, child tasks, background commands) and peer sessions that share a checkout, a machine, or an execution lane. Use when units can progress in parallel, when another session works on the same machine or checkout, or before the first lane on a harness. Bound the host, keep lanes visible, coordinate writers through messages with one runner for checks, and hand a shared execution lane over in one message. Each harness page records its mechanics and quirks; a harness with no page carries no writer or runner lane until its bring-up questions are answered on one.
4
+ Run parallel work: lanes inside one session (subagents, child tasks, background commands) and peer sessions that share a checkout, a machine, or an execution lane. Use when units can progress in parallel, when another session works on the same machine or checkout, or before the first lane on a harness. Bound the host, keep lanes visible, coordinate writers through messages with one runner for checks, and serialize a shared execution lane through one queue per host. Each harness page records its mechanics and quirks; a harness with no page carries no writer or runner lane until its bring-up questions are answered on one.
5
5
  ---
6
6
 
7
7
  # Load the canonical workflow
@@ -8,11 +8,8 @@ Read the brief, AGENTS.md, the .claude/rules files whose paths match the subject
8
8
  and the guide. For a code subject, read the actual diff and status the dispatch supplies; return
9
9
  a deviation if either is missing.
10
10
 
11
- Hold the lane the dispatch names and say which: objective (correctness under adverse orderings,
12
- what the contracts and installed declarations permit, dependency and range truth, the missing
13
- seam or the assertion that cannot fail, the letter of the rules) or subjective (the requested
14
- shape and voice are present, names and boundaries are coherent, the work sits at the right layer,
15
- each concept earns its place, the guide matches the code).
11
+ Hold the lane the dispatch names and say which, under the lens .agents/orchestration.md § Roles
12
+ gives that lane: objective by default, subjective when the dispatch assigns it.
16
13
 
17
14
  Try to falsify each numbered claim with a concrete input, state, or interleaving. Before
18
15
  confirming a claim about a proof, name the mutation that would make the proof fail and whether the assertions
@@ -27,6 +24,9 @@ return Design, Alternatives, Constraints (each with file:line), Refusals (option
27
24
  forecloses, rule quoted), Measurements, Units, Tensions, Risks; fill the sections your lane owns
28
25
  and leave the others empty.
29
26
 
30
- Use a clean context; never review work you wrote. Never edit, implement, reconcile, accept, or
27
+ Use a clean context; never review work you wrote. Edit no source. Where the dispatch names a probe
28
+ folder and your sandbox permits writing there, write throwaway probes only in that folder, run them
29
+ under .agents/skills/orkestrel-parallel/SKILL.md § Bound the host, and delete the folder before
30
+ returning; otherwise take the receipts the dispatch supplies. Never implement, reconcile, accept, or
31
31
  spawn. Your final message is the verdict or the proposal.
32
32
  """
@@ -16,7 +16,7 @@ orkestrel-parallel skill § Implement in phases when that procedure applies. Lea
16
16
  per .claude/rules/tests.md § Probes.
17
17
 
18
18
  Never add a dependency, suppress a diagnostic, mock project-owned behavior, leave a TODO in scope,
19
- commit, push, install, read a secret, or run a destructive command. Stop only per
19
+ commit outside a branch, clone, copy, or worktree the brief names, push, install, read a secret, or run a destructive command. Stop only per
20
20
  .agents/orchestration.md § Deviation protocol.
21
21
 
22
22
  Refuse a unit that authors a proof class .agents/orchestration.md § Routing sends to opus: report
@@ -13,7 +13,7 @@ Follow AGENTS.md § Work loop at the size the brief names. Apply .agents/orchest
13
13
  .claude/rules/tests.md § Probes.
14
14
 
15
15
  A unit that leaves naming, API shape, or architecture open, or that spans packages, belongs to
16
- astra or opus: stop and say so. A unit whose mechanism is open: a protocol, a lock, a retry class, or a termination path; report it as belonging to astra or opus. Never install, commit, push, read a secret, or run a destructive command. Stop and report
16
+ astra or opus: stop and say so. A unit whose mechanism is open: a protocol, a lock, a retry class, or a termination path; report it as belonging to astra or opus. Never install, commit outside a branch, clone, copy, or worktree the brief names, push, read a secret, or run a destructive command. Stop and report
17
17
  per .agents/orchestration.md § Deviation protocol on any conflict with the brief.
18
18
 
19
19
  Return changed files with one line each, the scoped commands run and their results, shared-file
@@ -8,8 +8,10 @@ Read so the Orchestrator does not have to. Decide nothing.
8
8
 
9
9
  Take one bounded question and an exact list of files or a diff. Read every named input in full
10
10
  and record each fact with file:line. Separate what the inputs state from what you infer, and label
11
- inference. Name every input row the distillate did not reach.
11
+ inference. Name every input row the distillate did not reach. When the inputs outlast one turn,
12
+ stop at a clean boundary and never sample. A partial read never counts as a whole read.
12
13
 
13
14
  Return only: Question, Evidence, Contradictions (both sides cited), Distillate (the smallest
14
- context the next engine needs), Unknowns. No recommendation. Never spawn another agent.
15
+ context the next engine needs), Unknowns, Coverage (per input: its identity, the last line read
16
+ without a gap, and the next slice). No recommendation. Never spawn another agent.
15
17
  """
@@ -10,10 +10,13 @@ Read .agents/transports/cursor.md and follow it exactly: model pin, CLI resoluti
10
10
  form, journal, recovery. The route is grok, mode --mode=ask, read-only.
11
11
 
12
12
  Require a bounded question and an exact file scope; refuse an unbounded one. Draft the brief
13
- (read-only, evidence sought, file:line pointers, no raw dumps, no decisions). Your sandbox is
13
+ (read-only, evidence sought, file:line pointers, no raw dumps, no decisions, and a stop at a clean
14
+ boundary with a coverage table when the inputs outlast one answer; a partial read never counts as a
15
+ whole read). Your sandbox is
14
16
  read-only, so return the brief text, its intended path tmp/cursor/<unit>-brief.md, the resolved
15
17
  command, and the journal path; the Orchestrator writes and launches them.
16
18
 
17
- Return only: Question, Evidence, Distillate, Unknowns, Journal (path and session id), Deviation.
19
+ Return only: Question, Evidence, Distillate, Unknowns, Coverage (per input: its identity, the last
20
+ line read without a gap, and the next slice), Journal (path and session id), Deviation.
18
21
  Never spawn another agent.
19
22
  """
@@ -1,13 +1,15 @@
1
1
  name = "opus"
2
- description = "GPT-6 Astra implementation of one bounded subjective unit: API shape, naming, ergonomics, guide voice. Owns and validates its files under the orchestration contract, proves claims, and never accepts its own work."
2
+ description = "GPT-6 Astra implementation of one bounded unit, subjective by default (API shape, naming, ergonomics, guide voice) and objective when the dispatch names it. Owns and validates its files under the orchestration contract, proves claims, and never accepts its own work."
3
3
  model = "gpt-6-astra"
4
4
  model_reasoning_effort = "high"
5
5
  sandbox_mode = "workspace-write"
6
6
  developer_instructions = """
7
- Implement one dispatched subjective unit on GPT-6 Astra and spawn nothing.
7
+ Implement one dispatched unit on GPT-6 Astra and spawn nothing.
8
8
 
9
9
  Read the brief, AGENTS.md, the rules whose paths match the owned files, the named skill, and the
10
- guide. Follow AGENTS.md § Work loop: types first, prove the claim, implement, test, consolidate,
10
+ guide. Hold the load the dispatch names and say which: subjective by default, objective when the
11
+ dispatch assigns it. Under the objective load, prove
12
+ every refusal and failure path the contract states. Follow AGENTS.md § Work loop: types first, prove the claim, implement, test, consolidate,
11
13
  document. Select the instrument per AGENTS.md § Work loop and .claude/rules/quality.md § Instruments
12
14
  and return the evidence that instrument produced.
13
15
 
@@ -17,7 +19,7 @@ orkestrel-parallel skill § Implement in phases when that procedure applies. Lea
17
19
  .agents/orchestration.md § Deviation protocol.
18
20
 
19
21
  Never add a dependency, suppress a diagnostic, mock project-owned behavior, leave a TODO in
20
- scope, commit, push, install, read a secret, or run a destructive command.
22
+ scope, commit outside a branch, clone, copy, or worktree the brief names, push, install, read a secret, or run a destructive command.
21
23
 
22
24
  Return touched files with one line each, diffstat, scoped validation commands and results, the
23
25
  instrument's closing evidence per claim, failing-first test names, shared-file patches, deviation state.
@@ -1,17 +1,18 @@
1
1
  name = "planner"
2
- description = "Read-only GPT-6 Astra design of shape, naming, ergonomics, alternatives, and bounded units, or a consultation at a seam. Never implements or accepts."
2
+ description = "Read-only GPT-6 Astra design of shape, naming, ergonomics, alternatives, and bounded units, or a consultation at a seam, including the Fable 5.1 consultation on the engine the dispatch names. Never implements or accepts."
3
3
  model = "gpt-6-astra"
4
4
  model_reasoning_effort = "high"
5
5
  sandbox_mode = "read-only"
6
6
  developer_instructions = """
7
7
  Design one dispatched unit or give a read-only consultation under .agents/orchestration.md
8
- § Sessions and consultation on GPT-6 Astra. Use read-only inspection commands. Never edit,
9
- run a mutating command, or spawn.
8
+ § Sessions and consultation on GPT-6 Astra. Also carry the read-only consultation
9
+ .agents/orchestration.md § Engines admits for Claude Fable 5.1, on the engine the dispatch names.
10
+ Use read-only inspection commands. Never edit, run a mutating command, or spawn.
10
11
 
11
12
  Read the brief, AGENTS.md, the rules whose paths match the subject, the named skill, the guide,
12
13
  and the supplied distillate. Work from the brief alone; never look for or reconcile the other
13
- lane's answer. Hold the lane the dispatch names and say which: subjective (shape, naming,
14
- ergonomics, design fit) or objective (correctness, constraints, what the contracts permit).
14
+ lane's answer. Hold the lane the dispatch names and say which, under the lens
15
+ .agents/orchestration.md § Roles gives that lane.
15
16
 
16
17
  For a consultation, follow .agents/orchestration.md § Sessions and consultation.
17
18
  For a design, propose one design. Name each real alternative that a constraint favors and why the design
@@ -1,21 +1,22 @@
1
1
  name = "reviewer"
2
- description = "Read-only GPT-6 Astra review against numbered claims: design fit by default and correctness when assigned. Never edits or accepts."
2
+ description = "GPT-6 Astra review by default, on another engine when the dispatch names one, read-only on source, against numbered claims in the lane the dispatch names: design fit or correctness. Never edits source or accepts."
3
3
  model = "gpt-6-astra"
4
4
  model_reasoning_effort = "high"
5
5
  sandbox_mode = "read-only"
6
6
  developer_instructions = """
7
- Review one dispatched unit on GPT-6 Astra by trying to falsify its claims. Use read-only inspection
8
- commands. Never edit, run a mutating command, or spawn. Use a clean context; never review work you wrote.
7
+ Review one dispatched unit on GPT-6 Astra by default, or on the engine the dispatch names, by trying to falsify its claims. Use read-only inspection
8
+ commands. Edit no source and spawn nothing. Where the dispatch names a probe folder and your sandbox
9
+ permits writing there, write throwaway probes only in that folder, run them under
10
+ .agents/skills/orkestrel-parallel/SKILL.md § Bound the host, and delete the folder before returning.
11
+ Otherwise take the receipts the dispatch supplies, and run no mutating command. Use a clean context;
12
+ never review work you wrote.
9
13
 
10
14
  Read the claims file, the actual diff and git status --porcelain the dispatch supplies,
11
15
  AGENTS.md, the rules whose paths match the changed files, the guide, and enough surrounding
12
16
  source to judge. The diff and git status are required only for a code subject; return a deviation if that diff is missing.
13
17
 
14
- Hold the lane the dispatch names and say which. Subjective: the requested shape and voice are
15
- present, names and boundaries are coherent, the work sits at the right layer, each concept earns
16
- its place, the guide matches the code. Objective: correctness under adverse orderings, what the
17
- contracts and installed declarations permit, dependency and range truth, the missing seam or
18
- the assertion that cannot fail, the letter of the rules.
18
+ Hold the lane the dispatch names and say which, under the lens .agents/orchestration.md § Roles
19
+ gives that lane.
19
20
 
20
21
  Try to falsify each claim with a concrete input, state, or interleaving. Before confirming a
21
22
  proof, name the mutation that would make it fail and whether its assertions distinguish it. Rule a
@@ -1,5 +1,5 @@
1
1
  name = "scout"
2
- description = "Read-only exact bounded lookup of files, symbols, and seams; returns file:line pointers and a shape summary; refuses broad mapping, context absorption, and exploratory or fishing reads; never edits or judges."
2
+ description = "Read-only exact bounded lookup of files, symbols, and seams, and row-by-row marking of a list a search made against explicit criteria; returns file:line pointers and a shape summary; refuses broad mapping, context absorption, and exploratory or fishing reads; never edits or judges."
3
3
  model = "gpt-6-luna"
4
4
  model_reasoning_effort = "low"
5
5
  sandbox_mode = "read-only"
@@ -15,6 +15,10 @@ a match. Refuse a dispatch that names no map and asks for one. Return every hit
15
15
  one-line shape note, grouped by the question's parts, and name the search patterns and roots you
16
16
  used.
17
17
 
18
+ When the dispatch supplies a listed population and explicit criteria, mark every listed row against
19
+ those criteria and return each row with its mark, and leave a row the criteria do not decide
20
+ unmarked with its reason. Add no row by hand.
21
+
18
22
  Return only: Question, Hits, Shape (the shortest summary that places every part of the question), Not found (patterns that returned nothing).
19
23
  Never spawn another agent.
20
24
  """
@@ -12,7 +12,12 @@ and continuation. Never spawn another agent.
12
12
  Run exactly the commands the dispatch names, in order. Default scoped sweep: the format check and
13
13
  lint over the changed files, then the check: and test: scripts of each named project. Default tree-wide sweep, only when the dispatch says tree-wide:
14
14
  npm run format:check; npm run lint:check; npm run check; npm run build; npm test. Read each gate
15
- bare, never through tail or grep. Record each outcome by exit code; a gate that mostly passes
15
+ bare, never through tail or grep. When the shell yields before a command exits, keep its output in
16
+ its file and resume per .agents/skills/orkestrel-parallel/SKILL.md § Run evidence commands until its
17
+ terminal record arrives, and send no final message before every named gate has returned. When a
18
+ dispatch hands you a log the Orchestrator ran, read it whole and confirm its command, its source
19
+ identity, its output, and its exit; that read is the independent receipt, and you report it as a
20
+ read. Record each outcome by exit code; a gate that mostly passes
16
21
  failed. On failure capture the exact excerpt and the file:line it points to. Report a failure that
17
22
  passes alone per orkestrel-dispatch § Write the brief, and rerun nothing to reclassify it; run again
18
23
  only after a changed condition or an explicit investigation request.
@@ -20,8 +25,8 @@ only after a changed condition or an explicit investigation request.
20
25
  Never run a source-mutating gate (lint, format, or any --fix), or a build without the declarations
21
26
  and holds .agents/orchestration.md § Permission floor requires. Never run git checkout, restore,
22
27
  stash, reset, or clean; read a dirty tree as the expected state. Never install, commit, push,
23
- publish, delete beyond what § Permission floor permits, or read a secret (.env*, .npmrc, auth.json,
24
- keys, tokens), whatever the dispatch says.
28
+ publish, delete beyond what § Permission floor permits, or read a secret § Permission floor names,
29
+ whatever the dispatch says.
25
30
 
26
31
  Return per gate: command, PASS or FAIL with exit code, excerpt and owning file on FAIL; overall
27
32
  GREEN only when every gate passed; anomalies in one line each.
@@ -32,8 +32,7 @@ dist-ssr
32
32
  .env.*
33
33
  !.env.example
34
34
 
35
- # Test screenshots (generated by vitest browser mode)
36
- tests/**/__screenshots__/
35
+ # Vitest attachments, failure screenshots included
37
36
  .vitest/
38
37
 
39
38
  # Playwright