@orkestrel/scaffold 0.0.109 → 0.0.111

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/dist/agents/templates/brief.md +5 -1
  2. package/dist/bin/main.js +1 -1
  3. package/dist/bin/main.js.map +1 -1
  4. package/dist/host/agents/orchestration.md +45 -39
  5. package/dist/host/agents/platforms/windows.md +5 -0
  6. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +6 -6
  7. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -4
  9. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +1 -0
  11. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +18 -15
  12. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +27 -15
  13. package/dist/host/agents/skills/orkestrel-journey/SKILL.md +4 -0
  14. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +5 -5
  15. package/dist/host/agents/skills/orkestrel-parallel/references/cloud.md +28 -0
  16. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +13 -13
  17. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +3 -1
  18. package/dist/host/agents/skills/orkestrel-publish/references/window.md +1 -1
  19. package/dist/host/agents/templates/brief.md +5 -1
  20. package/dist/host/agents/transports/codex.md +1 -1
  21. package/dist/host/claude/AGENTS.md +1 -2
  22. package/dist/host/claude/agents/astra.md +2 -2
  23. package/dist/host/claude/agents/builder.md +3 -2
  24. package/dist/host/claude/agents/opus.md +2 -2
  25. package/dist/host/claude/agents/reviewer.md +2 -2
  26. package/dist/host/claude/agents/verifier.md +1 -1
  27. package/dist/host/claude/rules/campaign.md +1 -0
  28. package/dist/host/claude/rules/quality.md +3 -1
  29. package/dist/host/claude/rules/tests.md +11 -1
  30. package/dist/host/claude/rules/workspace.md +7 -8
  31. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  32. package/dist/host/codex/agents/astra.toml +8 -4
  33. package/dist/host/codex/agents/builder.toml +3 -3
  34. package/dist/host/codex/agents/opus.toml +4 -3
  35. package/dist/host/codex/agents/reviewer.toml +2 -2
  36. package/dist/host/codex/agents/verifier.toml +3 -3
  37. package/dist/host/codex/config.toml +1 -1
  38. package/dist/host/cursor/rules/orchestration.mdc +1 -1
  39. package/dist/host/dotfiles/oxlintrc.json +1 -1
  40. package/dist/host/guides/scaffold.md +5 -5
  41. package/dist/host/manifest.json +46 -40
  42. package/dist/host/tests/config.test.ts +9 -2
  43. package/dist/host/tests/policy.test.ts +38 -0
  44. package/dist/host/tests/setupPolicy.ts +361 -8
  45. package/dist/src/core/index.cjs +10 -6
  46. package/dist/src/core/index.cjs.map +1 -1
  47. package/dist/src/core/index.d.cts +5 -3
  48. package/dist/src/core/index.d.ts +5 -3
  49. package/dist/src/core/index.js +10 -6
  50. package/dist/src/core/index.js.map +1 -1
  51. package/package.json +1 -1
@@ -4,19 +4,19 @@ T3 hosts Claude, Codex, and Cursor lanes as app-owned child tasks of a thread, a
4
4
 
5
5
  ## Mechanics
6
6
 
7
- | Question | T3 |
8
- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
- | Start | Read providers, models, options, and limits from `orchestrator_capabilities`. Use `delegate_task` for app-owned children, cross-provider work, requested model options, or worktree isolation. Create a top-level thread only when the user asks for one. |
10
- | Continue | Send an ordinary continuation to the child's `childThreadId` through `t3_thread_send`: `queue` for a separate request turn, `auto` for a reply or idle continuation, `steer` only for an in-flight change. |
11
- | Wake versus deliver | An async child's completion wakes the parent thread with a notification. A queued turn can finish with no notice (2026-10-23). |
12
- | Track | The full `taskId` the launch returns, the `childThreadId`, and the provider, model, and options actually applied. The `clientRequestId` is no lookup key. Thread ids change when the tool session changes, sometimes between launches. |
13
- | Background | A child runs commands through its provider's shell. T3 stops an idle provider session's process tree about 30 minutes after its last turn (2026-10-15). |
14
- | Isolation | `shared` uses the parent's checkout; `worktree` creates one from the parent's local commit, without uncommitted edits. |
15
- | Tools | Codex children reach `t3_thread_send`, `t3_thread_read`, and `t3_thread_wait` (probed 2026-10-22). |
16
- | Limits | A provider's usage limit acts as that provider's page states. T3 refuses delegation with `parent_not_active` while the parent thread is not active (2026-10-24); the Background row holds the idle stop. |
17
- | Host effects | Each child's shell opened console windows on a Windows host; six concurrent children made it unusable (2026-10-21). |
18
- | Visibility | A `delegate_task` child appears in the T3 app, where the user can stop it; a CLI started from a child's shell is hidden (the user's ruling of 2026-10-19). |
19
- | Capability map | The Claude and Codex columns of `.agents/orchestration.md` § Roles; Cursor lanes are readers. |
7
+ | Question | T3 |
8
+ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | Start | Read providers, models, options, and limits from `orchestrator_capabilities`. Use `delegate_task` for app-owned children, cross-provider work, requested model options, or worktree isolation. Create a top-level thread only when the user asks for one. A child task names its role and reads that role's charter first, or the brief inlines the charter's Do, Refuse, and Return lines, and the launch records the model and options actually applied beside the role. |
10
+ | Continue | Send an ordinary continuation to the child's `childThreadId` through `t3_thread_send`: `queue` for a separate request turn, `auto` for a reply or idle continuation, `steer` only for an in-flight change. Send a continuation that changes scope, acceptance, or authorization as a pointer to its `<unit>-brief-<n>.md`; send a bare message only for an unchanged objective. |
11
+ | Wake versus deliver | An async child's completion wakes the parent thread with a notification. A queued turn can finish with no notice (2026-10-23). |
12
+ | Track | The full `taskId` the launch returns, the `childThreadId`, and the provider, model, and options actually applied. The `clientRequestId` is no lookup key. Thread ids change when the tool session changes, sometimes between launches. |
13
+ | Background | A child runs commands through its provider's shell. T3 stops an idle provider session's process tree about 30 minutes after its last turn (2026-10-15). |
14
+ | Isolation | `shared` uses the parent's checkout; `worktree` creates one from the parent's local commit, without uncommitted edits. |
15
+ | Tools | Codex children reach `t3_thread_send`, `t3_thread_read`, and `t3_thread_wait` (probed 2026-10-22). |
16
+ | Limits | A provider's usage limit acts as that provider's page states. T3 refuses delegation with `parent_not_active` while the parent thread is not active (2026-10-24); the Background row holds the idle stop. |
17
+ | Host effects | Each child's shell opened console windows on a Windows host; six concurrent children made it unusable (2026-10-21). |
18
+ | Visibility | A `delegate_task` child appears in the T3 app, where the user can stop it; a CLI started from a child's shell is hidden. |
19
+ | Capability map | The Claude and Codex columns of `.agents/orchestration.md` § Roles; Cursor lanes are readers. |
20
20
 
21
21
  ## Quirks
22
22
 
@@ -66,6 +66,8 @@ overwrite receipts are written only where the work tree ignores `tmp/`.
66
66
  against the published tarball for material content. An exit of 2 is an unanswered comparison,
67
67
  never a moved dist: fetch and re-run rather than ruling a bump owed.
68
68
 
69
+ After any generator verb in a working tree, run `format:check` before the commit.
70
+
69
71
  Restore every pin the target holds with `scripts/swap.ts --restore` before the visit's first step, per
70
72
  [release.md](release.md) § Fix a dependency before it publishes, because the visit reads and
71
73
  proves registry ranges. A distribution proof run against a local tarball proves the local tarball.
@@ -162,7 +164,7 @@ Prepare a published package's layer in this order, after the visit has ruled the
162
164
  preparation commit already precedes the overwrite; this install regenerates the lockfile for the
163
165
  bumped manifest.
164
166
  3. **Sweep the self-pins**, per the following section: the bump moves the version class.
165
- 4. **Run each package's own `prepublishOnly` script to green.**
167
+ 4. **Run `prepublishOnly` to green in a fresh clone of the candidate commit, in the order the package's own chain fixes.** A release run executes every step whose inputs a failed step leaves valid and reports each result, so one clean-host run surfaces every independent fault.
166
168
  Run the visit and this script on a Node whose bundled npm meets the `MINIMUM_NPM_VERSION` floor a
167
169
  generated workspace declares in `devEngines`: the scripts spawn the npm CLI beside the running
168
170
  Node binary when one is there, so a `PATH` change reaches them only where none is.
@@ -163,7 +163,7 @@ the same status. Rule from the evidence, never from which cause reads likelier.
163
163
 
164
164
  ## Read the verdict from the registry
165
165
 
166
- - Confirm a layer with `node .agents/skills/orkestrel-publish/scripts/window.ts --confirm <name@version>...`, which re-reads the registry until it serves each version or the wait ends.
166
+ - Confirm a layer with `node .agents/skills/orkestrel-publish/scripts/window.ts --confirm <name@version>...`, which re-reads the registry until it serves each version or the wait ends. `--confirm` prints `results`; read that key.
167
167
 
168
168
  - Read `+ @orkestrel/<name>@<version>` in the upload's own journal as the accepted verdict, and
169
169
  advance the chain on it. The registry's read lags its processing by minutes, which the
@@ -42,7 +42,7 @@ RETURN_SHAPE through OUTPUT_MECHANISM. No process diary.
42
42
 
43
43
  ## Deviation contract
44
44
 
45
- Stop and report (expected, found, evidence, done or not done, one hypothesis) on OBJECTIVE_CONFLICT. Settle ANCILLARY_CHOICES yourself and record them.
45
+ Stop and report (expected, found, evidence, done or not done, one hypothesis) on OBJECTIVE_CONFLICT. Settle ANCILLARY_CHOICES yourself and record them. Enumerate the failure classes the unit may meet with the action each takes; anything else stops and reports.
46
46
 
47
47
  ## Acceptance criteria
48
48
 
@@ -52,8 +52,12 @@ Stop and report (expected, found, evidence, done or not done, one hypothesis) on
52
52
 
53
53
  **Observations, not criteria.** TIMING_SENSITIVE_OR_TREE_WIDE_GATES the unit reports and the Orchestrator re-runs.
54
54
 
55
+ **Estimate and stop.** ESTIMATED_COST of the unit and STOP_COST, the cost at which it stops and reports; the unit's report records the observed cost beside that estimate.
56
+
55
57
  **Measurement.** FIXTURE_KINDS: the realistic heavy loads a cost claim is read under, named by kind; the unit sizes and reads them per `.claude/rules/quality.md` § Performance.
56
58
 
57
59
  ## Review evidence
58
60
 
59
61
  The actual diff and `git status --porcelain` for a code change; the capture portfolio for a rendered surface; the proposal, the canon it must satisfy, and its motivation for a process proposal.
62
+
63
+ **Release bar.** RELEASE_BAR_OR_NONE: for a review brief, the observable consequences that make a finding outside the claims enter the terminal line; `none` puts every substantiated outside finding there.
@@ -6,7 +6,7 @@ Every driver that carries a brief to the Codex GPT-6 Astra bench follows this fi
6
6
 
7
7
  ```text
8
8
  CODEX_ASTRA_MODEL=gpt-6-astra effort high; xhigh only for a stated hard-reasoning need
9
- CODEX_MECHANICAL_MODEL=gpt-6.1-sol fully specified, taste-free units
9
+ CODEX_MECHANICAL_MODEL=gpt-6.1-sol a fully specified unit with a closed shape
10
10
  CODEX_READING_MODEL=gpt-6-luna absorption and research when the Cursor bench is dark; record the substitution
11
11
  ```
12
12
 
@@ -6,12 +6,11 @@
6
6
 
7
7
  - `.agents/skills/orkestrel-parallel/references/claude.md` owns starting, continuing, tracking, and backgrounding lanes in Claude Code, and its quirks. Choose continuation or a fresh context per `.agents/orchestration.md` § Sessions and consultation.
8
8
  - Serialize writing Workflow nodes, and give every `agent()` node a model alias from § Models and an effort.
9
- - Route an exact bounded lookup to `scout`, per `.agents/orchestration.md` § Routing.
10
9
  - Probe a bench with `node .agents/skills/orkestrel-dispatch/scripts/bench.ts`, launch a lane through `scripts/launch.ts`, and read its answer with `scripts/result.ts`, all from the dispatch skill. `.agents/platforms/<platform>.md` owns the host shell's quirks.
11
10
 
12
11
  ## Models
13
12
 
14
- - Use the aliases `haiku`, `sonnet`, and `opus` in role frontmatter, a Workflow node, and a per-invocation `model`. Never `fable`, never `inherit`, never a fixed model ID, and never a dispatch that takes its model from the session, including an `Explore` call or a Workflow node without `model`: Claude Fable 5.1 orchestrates and is never a subagent, except as the consultant `.agents/orchestration.md` § Engines admits.
13
+ - Use the aliases `haiku`, `sonnet`, and `opus` in role frontmatter, a Workflow node, and a per-invocation `model`. Never `fable`, except the consultant dispatch `.agents/orchestration.md` § Engines admits, which passes `model: fable` per invocation; never `inherit`, never a fixed model ID, and never a dispatch that takes its model from the session, including an `Explore` call or a Workflow node without `model`; `.agents/orchestration.md` § Engines owns where Claude Fable 5.1 may run.
15
14
  - Keep `CLAUDE_CODE_SUBAGENT_MODEL` at `sonnet` in the `env` object of `.claude/settings.json`. It serves a subagent that no role frontmatter and no dispatch assigned a model; frontmatter and a per-invocation `model` outrank it (measured 2026-10-08 on Claude Code 2.1.294: `general-purpose` took it, `Plan` did not). Never set `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`; it overrides every role.
16
15
  - An alias serves the model the installed Claude Code maps it to. After a model release, measure the mapping with `claude -p "Reply with the single word OK." --model <alias> --output-format json --max-turns 1` and read `modelUsage`; when a newer model answers by id and the alias lags, update Claude Code through the host's package manager and measure again. Claude Code 2.1.294 serves Haiku 5.5 as `haiku`, Sonnet 5.5 as `sonnet`, and Opus 5.5 as `opus` (measured 2026-10-08). When a measurement moves an alias, update, in the same change, the version each `.claude/agents/` charter names in its description and opening line and the rows of `.agents/orchestration.md` § Engines.
17
16
  - Run the main session on `fable` or `opus` at high effort. Apply `.agents/orchestration.md` § Cache; check Claude Code's documented behavior for the installed version, model, and provider before changing model options.
@@ -14,7 +14,7 @@ Read `.agents/transports/codex.md` and follow it exactly. It owns the command, t
14
14
 
15
15
  ## Do
16
16
 
17
- 1. Take the dispatch's brief, or write one to `tmp/codex/<unit>-brief.md` from the dispatch: objective, owned and off-limits files, acceptance criteria cheap-first, the `AGENTS.md` non-negotiables and the rules scoped to the owned paths, the guide, the return shape, and the deviation contract. The brief forbids installs, commits, pushes, credentials, destructive commands, shared-file edits, and tree-wide mutating gates, and tells the unit it is the sole writer in its checkout.
17
+ 1. Take the dispatch's brief, or write one to `tmp/codex/<unit>-brief.md` from the dispatch: objective, owned and off-limits files, acceptance criteria cheap-first, the `AGENTS.md` non-negotiables and the rules scoped to the owned paths, the guide, the return shape, and the deviation contract. The brief has the unit select the instrument per `AGENTS.md` § Work loop and `.claude/rules/quality.md` § Instruments and return the evidence that instrument produced. The brief forbids installs, commits, pushes, credentials, destructive commands, shared-file edits, and tree-wide mutating gates, and tells the unit it is the sole writer in its checkout.
18
18
  2. Run `node .agents/skills/orkestrel-dispatch/scripts/brief.ts --check <brief>` and fix every missing path.
19
19
  3. Resolve the `codex exec` command per the transport, as the `launch.ts` line it shows.
20
20
  4. Return the brief path, the resolved command, and the journal path. Do not launch; the Orchestrator launches under a cap and verifies with `git status --porcelain`, the diff, and scoped validation.
@@ -22,5 +22,5 @@ Read `.agents/transports/codex.md` and follow it exactly. It owns the command, t
22
22
  ## Refuse
23
23
 
24
24
  - A unit that needs no write: report it as misrouted to `analyst`.
25
- - A unit whose work is a negative test that authors a violation construct: report it as routed to `opus` per `.agents/orchestration.md` § Routing.
25
+ - A unit that authors a proof class `.agents/orchestration.md` § Routing sends to `opus`: report it as routed to `opus`.
26
26
  - A second writer in the same checkout.
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  name: builder
3
- description: 'Sonnet 5.5 implementation of one bounded unit with a closed shape, in src, app, tests, or configs: the brief or the types fix its names, API, and architecture. Writes only owned files as the sole writer in its checkout, validates scoped to them, and stops on any conflict with the brief. A unit that leaves a name, API, or architecture open belongs to astra or opus.'
3
+ description: 'Sonnet 5.5 implementation of a fully specified unit with a closed shape, in src, app, tests, or configs: the brief or the types fix its names, API, and architecture. Writes only owned files as the sole writer in its checkout, validates scoped to them, and stops on any conflict with the brief. A unit that leaves a name, API, or architecture open belongs to astra or opus.'
4
4
  tools: Read, Grep, Glob, Edit, Write, Bash
5
5
  model: sonnet
6
6
  effort: low
7
7
  permissionMode: acceptEdits
8
8
  ---
9
9
 
10
- On Claude Sonnet 5.5, you implement one bounded unit with a closed shape. The dispatch is the plan; do not re-plan.
10
+ On Claude Sonnet 5.5, you implement a fully specified unit with a closed shape. The dispatch is the plan; do not re-plan.
11
11
 
12
12
  ## Do
13
13
 
@@ -21,6 +21,7 @@ On Claude Sonnet 5.5, you implement one bounded unit with a closed shape. The di
21
21
  ## Refuse
22
22
 
23
23
  - A unit that leaves naming, API shape, or architecture open, or that spans packages: report it as belonging to `astra` or `opus`.
24
+ - 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`.
24
25
  - Installing, committing, pushing, reading a secret, or a destructive command.
25
26
 
26
27
  ## Return
@@ -12,7 +12,7 @@ On Claude Opus 5.5, you implement one dispatched unit and spawn nothing.
12
12
  ## Do
13
13
 
14
14
  1. Read the brief, `AGENTS.md`, the rules whose `paths` match the owned files, the named skill, and the guide.
15
- 2. Follow `AGENTS.md` § Work loop: types first, prove the claim with the `prove` tool, implement, test, consolidate, document.
15
+ 2. Follow `AGENTS.md` § Work loop: types first, prove the claim, implement, test, consolidate, document. Select the instrument per `AGENTS.md` § Work loop and `.claude/rules/quality.md` § Instruments and return the evidence that instrument produced.
16
16
  3. Write only the owned files; return an exact patch for a shared file.
17
17
  4. Validate read-only and scoped: the `check:` script of the touched project, the touched test file, then the touched project. Never run `format`, lint `--fix`, `build`, or the whole suite.
18
18
  5. Leave no probe behind, per `.claude/rules/tests.md` § Probes.
@@ -24,4 +24,4 @@ Adding a dependency, suppressing a diagnostic, mocking project-owned behavior, l
24
24
 
25
25
  ## Return
26
26
 
27
- Touched files with one line each, diffstat, scoped validation commands and results, the `prove` closing line per claim, failing-first test names, shared-file patches, deviation state. No process diary.
27
+ Touched files with one line each, diffstat, scoped validation commands and results, the instrument's closing evidence per claim, failing-first test names, shared-file patches, deviation state. No process diary.
@@ -11,7 +11,7 @@ On Claude Opus 5.5, you review by trying to falsify the claims. You hold no edit
11
11
 
12
12
  ## Do
13
13
 
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. Return a deviation if the diff is missing.
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
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.
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`.
@@ -24,4 +24,4 @@ Reviewing work you wrote or helped design; review runs in a clean context.
24
24
 
25
25
  ## Return
26
26
 
27
- The `orkestrel-falsify` verdict shape: numbered verdicts with evidence, findings outside the claims, tested-and-held, one terminal line. Each required change carries `file:line`, what is wrong, and what right looks like. Nothing else.
27
+ The `orkestrel-falsify` verdict shape: numbered verdicts with evidence, findings outside the claims, tested-and-held, one terminal line. Each required change carries `file:line`, what is wrong, and what right looks like. For a remedy that adds a mechanism per `.agents/orchestration.md` § Size gate, return the failing case and the violated property, never the mechanism. A dispatch-named skill that fixes another shape wins. Nothing else.
@@ -16,7 +16,7 @@ On Claude Haiku 5.5, run the requested gates and report their results. Write onl
16
16
  2. Read each gate bare. Never pipe it through `tail` or `grep`.
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
- 5. On a timing failure, request one coordinated isolated rerun and preserve both results. When that rerun fails, stop and report; run again only after a changed condition or an explicit investigation request.
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.
20
20
 
21
21
  ## Refuse
22
22
 
@@ -36,6 +36,7 @@ A package directory holds:
36
36
  - 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.
37
37
  - 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
38
  - 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.
39
+ - `plan.md` holds a harden campaign's claims, its release bar, and its deferral list, each deferred item with its trigger and its owner.
39
40
  - 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.
40
41
  - 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.
41
42
  - Record a prepared, unapplied change as text in `plan.md` or as a commit, never as a pointer to scratch.
@@ -15,7 +15,9 @@ These rules govern how a claim is established: the evidence read before a change
15
15
  - Read the authoritative `types.ts` and the decision-bearing implementation first-hand. Delegate bulk reading, never the owning decision.
16
16
  - Treat existing code, tests, `old/`, branches, and copied projects as evidence, not authority.
17
17
  - Research when the user asks, when comparing an upstream or legacy implementation, or when current external behavior changes the design. Use primary sources for external capabilities and the installed declarations for dependencies. Separate verified fact from inference.
18
- - For a broad API or production-readiness change, build a capability/defect matrix before editing. Every row ends as implement, repair, retain, or exclude with evidence. The matrix is the definition of done; fix it when the change starts. Record a finding outside it for the next matrix.
18
+ - A brief or ruling that restates or changes a pinned behavior cites the test that pins it and states what that test demands in the new state.
19
+ - A diagnosis that instruments a tracked file proves the instrumentation is gone by matching the file's digest before and after.
20
+ - For a broad API or production-readiness change, build a capability/defect matrix before editing. Every row ends as implement, repair, retain, or exclude with evidence. The matrix is the definition of done; fix it when the change starts. Record a finding outside it for the next matrix, or block on it when it stands above the change's release bar.
19
21
 
20
22
  ## Probes before arguments
21
23
 
@@ -44,6 +44,11 @@ These rules govern what a test asserts and where it lives, the cross-cutting and
44
44
  - 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.
45
45
  - 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.
46
46
  - 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.
47
+ - A test creates every directory it writes under and assumes no git-ignored path exists.
48
+ - A readiness wait resolves on parsed complete content, never on a file's existence.
49
+ - A browser case restores every runner global it changes before it ends.
50
+ - 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.
51
+ - When data a generator renders gains a new shape, the generator's test gains that shape before the data ships.
47
52
  - 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.
48
53
  - 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.
49
54
  - Do not create test files solely for `constants.ts`, barrels, error definitions, or `types.ts`.
@@ -174,7 +179,8 @@ A test that spawns a process, packs, installs, or drives a real build is a proof
174
179
  - A `distribution` proof reads `import.meta.env.MODE` and fails, rather than skips, on an unreachable
175
180
  registry under `--mode release`. The publish gate invokes it that way, so a proof that skips there
176
181
  passes the gate without ever proving the artifact installs. An ordinary local run may still skip.
177
- - Slow and hermetic is reason enough to isolate a proof; it need not touch an external service.
182
+ - Accept a process, race, or lock proof only under the suite load it ships in and at a repeat count the brief sets from the failure's nature and states with its reason, re-examined against the stop signals `.agents/orchestration.md` § Size gate names, reported as passes over runs by a `verifier`.
183
+ - Slowness decides a proof's budget and isolation inside the project its subject names, per `.claude/rules/workspace.md` § Test project matrix, and the proof need not touch an external service.
178
184
  - Where such a proof stays in a shared project, size its budget from a full contended run rather than from an isolated one. A budget that clears the isolated cost by a thin margin turns contention into a red gate reporting a timeout, which carries no diagnostic about the code and costs a full investigation to dismiss.
179
185
 
180
186
  ## Shared test infrastructure
@@ -199,6 +205,9 @@ Test helpers are shared infrastructure, not local test-file clutter.
199
205
  - Never reimplement a framework helper in tests or fixtures; import the real parser, signer, flattener, or other helper.
200
206
  - Prefer small customizable factories/stubs that seed inert data for a real scenario over repeated inline setup.
201
207
  - Helper names follow module-helper naming: `createFixtureServer`, `buildElement`, `appendItems`, `renderRows`, `waitForReady`, `extractDetail`.
208
+ - Re-prove a change to what a setup module imports with the build output set aside.
209
+ - A module reads no live host object at import; it reads one inside the function that needs it.
210
+ - A fixture that stands in for another package's platform behavior copies that package's own proof of the behavior rather than re-deriving it.
202
211
 
203
212
  Place helpers by environment:
204
213
 
@@ -263,6 +272,7 @@ Use the real browser as the system under test:
263
272
  - Do not replace DOM events, storage, observers, viewports, layout methods, pointer, or drag APIs unless the browser genuinely lacks one.
264
273
  - Prefer real nodes, events, styles/layout, and observers.
265
274
  - In a file compiled by a browser or Vue scope, never load `@vitest/browser-playwright` types; read `cdp()` as `unknown`, and narrow `send` and each reply with guards.
275
+ - A browser proof of layout, geometry, or visibility runs the tester frame unscaled at the declared viewport.
266
276
  - When a browser test moves the real pointer through CDP, move it to `(-1, -1)` in the case's `finally` block.
267
277
  - Centralize event factories: `createPointerEvent`, `createDragEvent`, `typeInput`, `fireTransitionEnd`.
268
278
  - Centralize DOM builders: `createButtonElement`, `createDropdownElements`, `createModalElement`.
@@ -168,7 +168,7 @@ one environment, so each is its own project:
168
168
 
169
169
  | Project | Files | Proves | Gate |
170
170
  | ------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
171
- | `policy` | `tests/policy.test.ts` | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, bridges, and text integrity | `test` |
171
+ | `policy` | `tests/policy.test.ts` | The path- and text-shaped policy laws: mirrors, suppressions, the rule map, filenames, manifest scripts, skills, bridges, text integrity, and a tracked TypeScript specifier that resolves into `dist/` | `test` |
172
172
  | `config` | `tests/config.test.ts` | Root configuration resolves its aliases, projects, and outputs, and the `configs/` leaves behind them | `test` |
173
173
  | `setup` | `tests/setup*.test.ts` other than either `setup:browser` proof | Prove root setup behavior in Node with `setup.ts`. | `test` |
174
174
  | `setup:browser` | `tests/setupBrowser.test.ts`, `tests/setupStyles.test.ts` | Prove browser and style setup behavior in Playwright Chromium with `setup.ts` and `setupBrowser.ts`. | `test` |
@@ -209,7 +209,7 @@ one environment, so each is its own project:
209
209
  subjects, not names for one.
210
210
  Keep `conformance` in `test`: measure this package against an installed official artifact, and start
211
211
  any server the proof drives itself. Keep `tree` in `test`: read the real tree in Node and drive no
212
- build, install, or service. Keep `integration` in `test`: compose the workspace's public
212
+ build, install, or service. Keep `integration` in `test` whatever its cost: compose the workspace's public
213
213
  surfaces without packing, installing, or driving an external service. In a publishing workspace,
214
214
  run `distribution`, `studies`, and `service` from `prepublishOnly`: pack and install the package in
215
215
  `distribution`, run the authored study proofs in `studies` after `npm test` and before the release
@@ -223,18 +223,17 @@ throwaway instrument against real sources, aliases and setup. Declare no proof t
223
223
  project composed in the root configuration rather than declared as a path string. The `probe` MCP
224
224
  server arms through it — its arming specifications live under the `tmp/probes/` directory and infer
225
225
  this project — so a workspace that removes the project, or declares it as a path string, fails the
226
- server's arming, and an unarmed server refuses every `prove` call. The `test:bench` script runs the
227
- same project in benchmark mode, which collects every test file under the `tmp/probes/` directory and
228
- the `tests/` tree while refusing every ordinary test case. Every test script names its project and
229
- the `test:bench` script joins no chain, so no gate runs either mode; the project's directory is
226
+ server's arming, and an unarmed server refuses every `prove` call. `test:bench` runs the bench
227
+ project over `*.bench.ts` files under `tests/` and `tmp/probes/` and collects no ordinary test file.
228
+ Every test script names its project and the `test:bench` script joins no chain, so no gate runs
229
+ either project; the project's directory is
230
230
  ignored by git; and `.claude/rules/tests.md` governs what may live there.
231
231
 
232
232
  - Define a cross-cutting project only for a proof the package actually has.
233
233
  - Prepare the external service before invoking the `service` project. Use `tests/setupService.ts`
234
234
  to verify readiness, apply `.claude/rules/tests.md`, and name the project `service` whatever it
235
235
  drives.
236
- - In a publishing workspace, a project leaves the default run when it drives a live external
237
- service or is hermetic but slow — it spawns processes, packs, installs, or drives a real build.
236
+ - The proof's subject decides its project, and its cost decides only its budget and isolation inside that project.
238
237
  - Give every isolated project its own script, and place that script by the preceding paragraph.
239
238
 
240
239
  Setup assets:
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: orkestrel-harden
3
- description: Research, audit, refactor, implement, centralize, test, document, and locally verify an individual Orkestrel TypeScript package to enterprise-grade production readiness under the repository's current AGENTS.md. Use when asked to fill missing or deferred capabilities, compare upstream or legacy implementations, salvage prior art, centralize source or test declarations, eliminate nested functions or superfluous wrappers, maximize declared @orkestrel dependencies—especially @orkestrel/contract—or add rigorous real-implementation and live-service tests. Select only the phases required by a narrow request; run the full workflow for production readiness or comprehensive hardening. A guide, README, or TSDoc pass on one package runs the document phase alone.
3
+ description: Research, audit, refactor, implement, centralize, test, document, and locally verify an individual Orkestrel TypeScript package to enterprise-grade production readiness of its own contract on its supported hosts under the repository's current AGENTS.md. Use when asked to fill missing or deferred capabilities, compare upstream or legacy implementations, salvage prior art, centralize source or test declarations, eliminate nested functions or superfluous wrappers, maximize declared @orkestrel dependencies—especially @orkestrel/contract—or add rigorous real-implementation and live-service tests. Select only the phases required by a narrow request; run the full workflow for production readiness or comprehensive hardening. A guide, README, or TSDoc pass on one package runs the document phase alone.
4
4
  ---
5
5
 
6
6
  # Load the canonical workflow
@@ -7,8 +7,9 @@ developer_instructions = """
7
7
  Implement one dispatched unit and spawn nothing.
8
8
 
9
9
  Read the brief, AGENTS.md, the .claude/rules files whose paths match the owned files, the named
10
- skill, and the guide. Follow AGENTS.md § Work loop: types first, prove the claim with the prove
11
- tool, implement, test, consolidate, document.
10
+ skill, and the guide. Follow AGENTS.md § Work loop: types first, prove the claim, implement,
11
+ test, consolidate, document. Select the instrument per AGENTS.md § Work loop and
12
+ .claude/rules/quality.md § Instruments and return the evidence that instrument produced.
12
13
 
13
14
  Write only the owned files; return an exact patch for a shared file. Validate read-only and scoped:
14
15
  the touched project's check: script, the touched test file, then the touched project. Never run
@@ -19,6 +20,9 @@ Never add a dependency, suppress a diagnostic, mock project-owned behavior, leav
19
20
  commit, push, install, read a secret, or run a destructive command. Stop only per
20
21
  .agents/orchestration.md § Deviation protocol.
21
22
 
22
- Return touched files with one line each, diffstat, scoped validation results, the prove closing
23
- line per claim, failing-first test names, shared-file patches, deviation state. No process diary.
23
+ Refuse a unit that authors a proof class .agents/orchestration.md § Routing sends to opus: report
24
+ it as routed to opus.
25
+
26
+ Return touched files with one line each, diffstat, scoped validation results, the instrument's
27
+ closing evidence per claim, failing-first test names, shared-file patches, deviation state. No process diary.
24
28
  """
@@ -1,10 +1,10 @@
1
1
  name = "builder"
2
- description = "Sol executor for one bounded unit with a closed shape in src, app, tests, or configs; writes only owned files as the sole writer in its checkout and validates scoped to them."
2
+ description = "Sol executor for a fully specified unit with a closed shape in src, app, tests, or configs; writes only owned files as the sole writer in its checkout and validates scoped to them."
3
3
  model = "gpt-6.1-sol"
4
4
  model_reasoning_effort = "low"
5
5
  sandbox_mode = "workspace-write"
6
6
  developer_instructions = """
7
- Implement one bounded unit with a closed shape. The dispatch is the plan; do not re-plan.
7
+ Implement a fully specified unit with a closed shape. The dispatch is the plan; do not re-plan.
8
8
 
9
9
  Read the brief, the .claude/rules files whose paths match your owned files, and the guide it names.
10
10
  Write only the owned files; return an exact patch for a shared file. Follow AGENTS.md § Work loop
@@ -13,7 +13,7 @@ touched project when the brief names it. Validate read-only and scoped: a non-fi
13
13
  scoped check: script, the touched tests; never run format, lint --fix, build, or the whole suite. Leave no probe behind, per .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. 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, 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
@@ -7,8 +7,9 @@ developer_instructions = """
7
7
  Implement one dispatched subjective 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 with the prove tool, implement,
11
- test, consolidate, document.
10
+ guide. Follow AGENTS.md § Work loop: types first, prove the claim, implement, test, consolidate,
11
+ document. Select the instrument per AGENTS.md § Work loop and .claude/rules/quality.md § Instruments
12
+ and return the evidence that instrument produced.
12
13
 
13
14
  Write only the owned files; return an exact patch for a shared file. Validate read-only and
14
15
  scoped: the touched project's check: script, the touched test file, then the touched project.
@@ -20,6 +21,6 @@ Never add a dependency, suppress a diagnostic, mock project-owned behavior, leav
20
21
  scope, commit, push, install, read a secret, or run a destructive command.
21
22
 
22
23
  Return touched files with one line each, diffstat, scoped validation commands and results, the
23
- prove closing line per claim, failing-first test names, shared-file patches, deviation state.
24
+ instrument's closing evidence per claim, failing-first test names, shared-file patches, deviation state.
24
25
  No process diary.
25
26
  """
@@ -9,7 +9,7 @@ commands. Never edit, run a mutating command, or spawn. Use a clean context; nev
9
9
 
10
10
  Read the claims file, the actual diff and git status --porcelain the dispatch supplies,
11
11
  AGENTS.md, the rules whose paths match the changed files, the guide, and enough surrounding
12
- source to judge. Return a deviation if the diff is missing.
12
+ source to judge. The diff and git status are required only for a code subject; return a deviation if that diff is missing.
13
13
 
14
14
  Hold the lane the dispatch names and say which. Subjective: requested shape and voice, coherent
15
15
  names and boundaries, the right layer, each concept's purpose, guide parity. Objective:
@@ -25,5 +25,5 @@ as a proposal to test against the code, never as authority.
25
25
 
26
26
  Return the orkestrel-falsify verdict shape: numbered verdicts with evidence, findings outside the
27
27
  claims, tested-and-held, one terminal line. Each required change carries file:line, what is
28
- wrong, and what right looks like. Nothing else. Your final message is the verdict.
28
+ wrong, and what right looks like. For a remedy that adds a mechanism per `.agents/orchestration.md` § Size gate, return the failing case and the violated property, never the mechanism. A dispatch-named skill that fixes another shape wins. Nothing else. Your final message is the verdict.
29
29
  """
@@ -13,9 +13,9 @@ Run exactly the commands the dispatch names, in order. Default scoped sweep: the
13
13
  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
15
  bare, never through tail or grep. Record each outcome by exit code; a gate that mostly passes
16
- failed. On failure capture the exact excerpt and the file:line it points to. On a timing failure, request one coordinated isolated rerun and preserve both results. When that
17
- rerun fails, stop and report; run again only after a changed condition or an explicit investigation
18
- request.
16
+ failed. On failure capture the exact excerpt and the file:line it points to. Report a failure that
17
+ passes alone per orkestrel-dispatch § Write the brief, and rerun nothing to reclassify it; run again
18
+ only after a changed condition or an explicit investigation request.
19
19
 
20
20
  Never run a source-mutating gate (lint, format, or any --fix), or a build without the declarations
21
21
  and holds .agents/orchestration.md § Permission floor requires. Never run git checkout, restore,
@@ -21,7 +21,7 @@ before relying on a capability those pages name. .agents/platforms/ owns the hos
21
21
 
22
22
  Hooks: .codex/hooks.json runs the orkestrel-dispatch sweep script (node
23
23
  .agents/skills/orkestrel-dispatch/scripts/sweep.ts --report) on SessionStart and git diff --check
24
- on Stop. Every script an agent writes is TypeScript run by node, per AGENTS.md.
24
+ on Stop.
25
25
  """
26
26
 
27
27
  [agents]
@@ -9,7 +9,7 @@ alwaysApply: true
9
9
 
10
10
  ## Posture
11
11
 
12
- - Invoked through the `grok` bridge (`agent -p --mode=ask`): act as a read-only executor. Return distilled evidence with `file:line` pointers. Never edit, decide, or accept.
12
+ - Invoked through the `grok` bridge (`agent -p --mode=ask`): act as the `grok` role per `.agents/orchestration.md` § Roles and § Engines. Return distilled evidence with `file:line` pointers.
13
13
  - Driven by the user: act as the Orchestrator per `.agents/orchestration.md`, on Grok.
14
14
  - `.agents/skills/orkestrel-parallel/references/cursor.md` owns Cursor's lane mechanics and quirks; `.agents/platforms/` owns the host shell.
15
15
 
@@ -818,7 +818,7 @@
818
818
  }
819
819
  },
820
820
  {
821
- "files": ["tests/setup*.test.ts"],
821
+ "files": ["tests/setup*.test.ts", "tests/setup*.bench.ts"],
822
822
  "rules": {
823
823
  "no-restricted-imports": [
824
824
  "error",
@@ -2012,9 +2012,9 @@ question, and a person decides whether the generated toolchain supports it.
2012
2012
 
2013
2013
  `TOOLCHAIN_HOLDS` records framework-specific ranges. `blueprintToToolchainHolds` selects those
2014
2014
  rows from the blueprint's occupied browser framework faces. A `src/vue` or `app/vue` face selects
2015
- TypeScript `^6.0.3`: no stable `vue-tsc` runs on TypeScript 7, `@volar/typescript@2.4.30` declares
2016
- the peer range `typescript <7`, and the TypeScript 7.0 announcement directs Vue projects to stay
2017
- on TypeScript 6.0. Every workspace without that extension receives TypeScript `^7.0.2`.
2015
+ TypeScript `^6.0.3`: no stable `vue-tsc` runs on TypeScript 7, `vue-tsc` resolves
2016
+ `typescript/lib/tsc`, which TypeScript 7.0.2 does not export, and the TypeScript 7.0 announcement
2017
+ directs Vue projects to stay on TypeScript 6.0. Every workspace without that extension receives TypeScript `^7.0.2`.
2018
2018
  For a selected hold, `audit` reports the hold and its reason in place of the newer-major question
2019
2019
  and reports a declaration past the hold. A non-Vue workspace on TypeScript 7 raises no hold
2020
2020
  question. The constants proof ties each hold to its framework's planned range and scaffold's
@@ -2935,8 +2935,8 @@ The generated guide index lists each occupied Vue face with its source, tests, a
2935
2935
  rendering, and the failure envelope.
2936
2936
  - [`tests/src/bin/main.test.ts`](../tests/src/bin/main.test.ts) — the process entry point.
2937
2937
  - [`tests/policy.test.ts`](../tests/policy.test.ts) — the path- and text-shaped policy laws:
2938
- mirrors, the root setup mirror, suppressions, the rule map, filenames, manifest scripts, skills,
2939
- bridges, the prose sweep over every authored Markdown file, and the text-integrity sweep over the
2938
+ mirrors, the root setup mirror, suppressions, imports into `dist/`, the rule map, filenames, manifest
2939
+ scripts, skills, bridges, the prose sweep over every authored Markdown file, and the text-integrity sweep over the
2940
2940
  authored and source text. The syntax-shaped laws are the
2941
2941
  rules of the vendored oxlint plugin `configs/policy.ts`, proven in `tests/config.test.ts`.
2942
2942
  - [`tests/config.test.ts`](../tests/config.test.ts) — the root configuration's aliases, projects,