@orkestrel/scaffold 0.0.104 → 0.0.105

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.
@@ -84,9 +84,9 @@ A large change runs these phases once each, in order, and ends when the exit cri
84
84
 
85
85
  - Fan out when the work is many small, fully specified, disjoint units: one cheap agent per unit with minimal context. Give the agents the same model, effort, agent type, tools, schema, and working directory when isolation and routing allow it, so their prompts share one cache prefix.
86
86
  - Judgment stays narrow: a design or review pass is at most the two lanes the size gate names, each in a clean context, blind to the other, and it runs once. Never fan judgment out further, and never run it as a loop.
87
- - One writer per checkout. Give parallel writers disjoint owned files; give a writer its own worktree under `tmp/worktrees/` only when two units must write the same files at once. Commit a checkpoint before a writing dispatch.
88
- - Shared files are report-only; a unit returns an exact patch.
89
- - Concurrent units validate read-only and scoped to their owned files. Never run tree-wide `format`, lint `--fix`, or `build` beside a live unit.
87
+ - One writer per checkout, except under `orkestrel-parallel`: there, at most three writers share one checkout, each owns disjoint files and disjoint regions of shared files, and one runner lane owns every test, check, and build process. Otherwise give parallel writers disjoint owned files, and give a writer its own worktree under `tmp/worktrees/` only when two units must write the same files at once. Commit a checkpoint before a writing dispatch.
88
+ - Shared files are report-only; a unit returns an exact patch. Under `orkestrel-parallel`, a writer edits its owned regions of a shared file directly.
89
+ - Concurrent units validate read-only and scoped to their owned files; under `orkestrel-parallel`, the runner also runs read-only root checks and reports each finding to the lane that owns its file. Never run tree-wide `format`, lint `--fix`, or `build` beside a live unit.
90
90
  - One Grok lane at a time; queue the rest. An empty lane beside a live probe is starvation, not darkness.
91
91
  - The Orchestrator's own sweep is a writing dispatch: run it before or after the units, never beside them.
92
92
 
@@ -0,0 +1,72 @@
1
+ ---
2
+ name: orkestrel-parallel
3
+ description: >-
4
+ Run several writer lanes in one checkout at the same time, coordinated by messages: writers edit owned regions in phases, one runner lane owns every test and check process, and the Orchestrator rules and mediates. Use when a campaign has three or more units whose files are mostly disjoint and whose shared files are a few kind files, guides, or entry tests. Do not use it when two units rewrite the same region, when a unit needs a quiet tree for a measurement, or when the harness gives lanes no shared file system or no message channel that wakes an idle lane.
5
+ ---
6
+
7
+ # Parallel lanes
8
+
9
+ ## Lanes
10
+
11
+ | Lane | Role | Owns | Never |
12
+ | ------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
13
+ | Orchestrator | the harness's own engine | the protocol, the roster, launches, rulings, holds, acceptance, commits | delegates acceptance |
14
+ | `runner` | `verifier` on the native small engine | every test, typecheck, lint, format, build, and citation process; its log, run files, and result files under `coord/` | writes outside `coord/`; runs an unrequested command |
15
+ | writer (`w<unit>`) | `builder`, `astra`, or `opus` by `.agents/orchestration.md` § Routing | its owned files, its owned regions of shared files, and its log | runs a test, check, lint, format, or build process |
16
+ | reviewer | `analyst` or `reviewer`, independent of the lane's writer per `.agents/orchestration.md` § Engines | a read-only verdict on the work the size gate sends it | edits, writes, runs, or messages |
17
+
18
+ - Run at most three writers and one runner. Keep every live lane, reviewers included, inside the harness's concurrency limit (`references/harnesses.md`), and queue a lane that does not fit.
19
+ - Before launch, assign every file region to exactly one writer. A shared file is owned by region (a doc block, a table, a guide section, a list entry), never as a whole.
20
+
21
+ ## Set up
22
+
23
+ 1. Commit the accepted state; every lane starts from one commit.
24
+ 2. Write `tmp/units/<round>/coord/protocol.md`: the path of this skill, the round's lanes, each writer's owned files and regions, and each writer's acceptance commands. Write `coord/roster.md` (lane, role, address, Orchestrator address). Create `coord/results/` and `coord/runs/`.
25
+ 3. Launch the runner first. Its first turn logs `ready` with its address and ends.
26
+ 4. Launch the writers one at a time. Fill each roster row from its launch result; after launch, send each lane that messages peers their addresses.
27
+ 5. For a lane already running, send one in-flight message naming the protocol, its lane name, its log, and its next request number.
28
+
29
+ ## Channels
30
+
31
+ - File channel: each writer and the runner append only to their own log, `coord/<lane>.md`, one line per event: `<lane> | <request or phase> | <kind> | <text>`. Never write another lane's log. A reviewer returns its verdict to the Orchestrator and writes nothing.
32
+ - Push channel (`references/harnesses.md`): requests queue to the runner one turn each, in arrival order; replies and rulings join the receiver's running turn or start one.
33
+ - Number requests from 1 per lane across the whole round, fix units included, and never reuse a number.
34
+ - Results: the runner writes each result under a temporary name in `coord/results/`, renames it to `coord/results/<lane>-<n>.md` when it is complete, then replies. A waiting writer polls for that file; a lost message does not stall it.
35
+ - Request format:
36
+
37
+ ```
38
+ REQUEST <lane>-<n>
39
+ from: <lane> <address>
40
+ commands:
41
+ 1. <exact command>
42
+ expect: <red or green per command, with case names>
43
+ ```
44
+
45
+ - Escalation: send the Orchestrator `ESCALATE <lane>: expected, found, evidence, proposed action`. Continue the work the question does not block. The ruling arrives in your turn; record any scope extension in your report.
46
+ - A writer can message another writer a cross-lane fact (a line it added, a window it opens). Rulings come only from the Orchestrator.
47
+
48
+ ## Writers
49
+
50
+ - Work in phases and log each: `types` (types and API docs), `red` (failing-first cases, then a red-run request), `source` (the change, then a green-run request), `docs` (guide sentences).
51
+ - In a shared file, edit small, complete hunks inside your owned regions. Re-read the region immediately before each patch, never rewrite a whole file, and leave every hunk syntactically complete. When a patch fails on changed context, re-read and re-apply.
52
+ - Request every test, check, lint, format, and build process from the runner. Read-only shell and search commands stay yours.
53
+ - Run no formatter. Fix a format finding by hand; when the finding names only a file, ask the Orchestrator for the exact hunk.
54
+ - Before a temporary mutation (a mutation proof), ask the runner to hold unrelated runs and each lane that owns a region of the mutated file to hold its edits, and mutate only after each has logged `held`. Restore the exact text, confirm with `git diff`, log `restored`, and tell them.
55
+ - When done and green, log `done`, send the runner `FINAL <lane>`, write your report, and end your task.
56
+
57
+ ## Runner
58
+
59
+ - Before each command, wait until no test or typecheck process runs in this checkout, excluding editor language services. Bound the wait by the request's expected run time. When any conflicting process exceeds that budget, report its recorded ownership, process id, and command line to the Orchestrator and suspend the request for a ruling. Never kill a process yourself. For a capped run, have the Orchestrator apply the `orkestrel-dispatch` skill's launch reference § Kill and relaunch before releasing the affected files or starting another command.
60
+ - Launch each command through `node .agents/skills/orkestrel-dispatch/scripts/launch.ts` under a cap sized from prior runs, with `--journal coord/runs/<lane>-<n>-<k>.txt` and `--errors coord/runs/<lane>-<n>-<k>.err`, and log the process id it prints. When the shell returns before the launcher ends, resume its tracked shell session until the launcher exits, then read both files and require the terminal exit record. Track descendant process ids while their parent lives, and confirm that the command and its descendants have ended before publishing completion; otherwise escalate under the preceding wait rule.
61
+ - Report each finding only to the lane that owns its file.
62
+ - Serve the commands each writer's acceptance criteria name, plus the standing list: the root typecheck, the scoped typecheck, the guide parity check, the package entry test, and lint or format checks over paths the writer names. Run each read-only; none writes the tree.
63
+ - After every writer's current `FINAL` has arrived, wait for the Orchestrator's closing request naming a unique gate number and confirming acknowledged write holds. Run the root typecheck, scoped typecheck, every acceptance test file alone, the guide parity check, and lint and format checks over every path `git status --porcelain` lists. Publish the complete result atomically as `coord/results/closing-<k>.md`, reply with that gate number, and end your task.
64
+
65
+ ## Orchestrator
66
+
67
+ - Before ruling on an escalation, reproduce its evidence at its cited lines. Bound every ruling: what to change, what to leave.
68
+ - When a format check names only a file, inspect the file and send the writer the exact formatting hunk. After the writer applies it, request a read-only format check from the runner.
69
+ - Run the review `.agents/orchestration.md` § Size gate names, and supply its diff and status. A unit's review can start read-only when its lane logs `done`, while the others write; a campaign's `orkestrel-falsify` round runs on the integrated result after the closing gate.
70
+ - Before resuming a writer for a fix unit, send the runner that lane's `FINAL` invalidation and wait for acknowledgment; every other lane's `FINAL` stands. Follow `references/harnesses.md` to resume the writer's lane or dispatch its successor. If a closing gate is active, keep the reopened writer read-only until that gate completes.
71
+ - Before requesting a closing gate, obtain write-hold acknowledgments from every live writer and hold your own source edits. Allocate a gate number never used earlier in the round. Keep those holds until the matching complete result is published. After a fix unit, request another gate covering the affected checks and acceptance tests.
72
+ - After the last green gate and the review the size gate names, commit. When shared files mix several units' hunks, commit the batch once and name each unit, its engine, and each fix unit in the message.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: 'Orkestrel Parallel'
3
+ short_description: 'Coordinate writer lanes and one runner in a shared checkout'
4
+ default_prompt: 'Use $orkestrel-parallel to coordinate writers in one checkout with owned regions, queued checks, and Orchestrator rulings.'
@@ -0,0 +1,12 @@
1
+ # Harness mechanics
2
+
3
+ | Harness | Launch | Own address | Push channel | Limits |
4
+ | ----------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
5
+ | T3 (any provider) | `delegate_task` with `isolation: "shared"`, `mode: "async"`, a stable `clientRequestId` | `parentThreadId` from `orchestrator_capabilities` | `t3_thread_send`: `queue` for a request (one turn per message, arrival order), `auto` for a reply or ruling, `steer` to change a running lane's instructions; `t3_thread_read` and `t3_thread_wait` to read a lane | a lane address embeds the Orchestrator's MCP session, which can change between launches: write each roster row from its launch result |
6
+ | Claude Code | the `Agent` tool, background by default | the agent id or name the launch returns | the Orchestrator sends `SendMessage` to a running subagent; a subagent without a message tool uses the file channel and the Orchestrator relays | the dispatch aliases `.claude/AGENTS.md` names |
7
+ | Codex | native agents or the CLI (`.agents/transports/codex.md`); under T3, the T3 row | the session id the launch returns | the native message and follow-up tools where the session exposes them; otherwise the T3 row when Codex runs under T3 | `max_concurrent_threads_per_session` in `.codex/config.toml` caps native agents; the shell tool returns after its yield time and leaves the command running, so write output to a file and poll the process or resume the shell session |
8
+ | Cursor | the CLI (`.agents/transports/cursor.md`) | the session id the launch returns | none, so a Cursor lane holds no writer or runner lane | the routing `.agents/orchestration.md` § Routing gives Cursor |
9
+
10
+ - Where the harness resumes an ended lane with its context, as T3 does, send the lane's fix unit to that lane; otherwise dispatch a successor brief carrying the lane's report and the fix scope.
11
+ - Under T3, retain the task id each send returns. A completion notice for a turn another lane started can miss the Orchestrator: after the last `FINAL` is sent, read the runner's `coord/results/closing-<k>.md` or its task status instead of waiting for the notice. Never brief the runner to wait inside a turn, which blocks every queued request.
12
+ - In every Codex brief, state how the lane waits on a long command: output to a file, then poll the process or resume the shell session.
@@ -56,8 +56,8 @@ so network-controlled descriptions never enter agent instruction context.
56
56
  | `@orkestrel/csv` | `0.0.10` | L1 | `@orkestrel/contract` `^0.0.19` | |
57
57
  | `@orkestrel/database` | `0.0.18` | L2 | `@orkestrel/sqlite` `^0.0.14`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/indexeddb` `^0.0.14` | |
58
58
  | `@orkestrel/emitter` | `0.0.12` | L1 | `@orkestrel/contract` `^0.0.19` | |
59
- | `@orkestrel/form` | `0.0.12` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
60
- | `@orkestrel/guide` | `0.0.24` | L3 | `@orkestrel/contract` `^0.0.19`, `@orkestrel/markdown` `^0.0.17` | |
59
+ | `@orkestrel/form` | `0.0.13` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
60
+ | `@orkestrel/guide` | `0.0.25` | L3 | `@orkestrel/contract` `^0.0.19`, `@orkestrel/markdown` `^0.0.17` | |
61
61
  | `@orkestrel/html` | `0.0.12` | L1 | `@orkestrel/contract` `^0.0.19` | |
62
62
  | `@orkestrel/indexeddb` | `0.0.14` | L1 | `@orkestrel/contract` `^0.0.19` | |
63
63
  | `@orkestrel/interpret` | `0.0.16` | L3 | `@orkestrel/reason` `^0.0.13`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/template` `^0.0.10` | |
@@ -67,7 +67,7 @@ so network-controlled descriptions never enter agent instruction context.
67
67
  | `@orkestrel/middleware` | `0.0.25` | L4 | `@orkestrel/abort` `^0.0.13`, `@orkestrel/budget` `^0.0.14`, `@orkestrel/timeout` `^0.0.13`, `@orkestrel/contract` `^0.0.19` | `@orkestrel/server` `^0.0.23`, `@orkestrel/database` `^0.0.18` |
68
68
  | `@orkestrel/msg` | `0.0.13` | L1 | `@orkestrel/contract` `^0.0.19` | |
69
69
  | `@orkestrel/ndjson` | `0.0.12` | L1 | `@orkestrel/contract` `^0.0.19` | |
70
- | `@orkestrel/ollama` | `0.0.24` | L6 | `@orkestrel/tool` `^0.0.19`, `@orkestrel/agent` `^0.0.31`, `@orkestrel/budget` `^0.0.14`, `@orkestrel/ndjson` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
70
+ | `@orkestrel/ollama` | `0.0.25` | L6 | `@orkestrel/tool` `^0.0.19`, `@orkestrel/agent` `^0.0.31`, `@orkestrel/budget` `^0.0.14`, `@orkestrel/ndjson` `^0.0.12`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/process` `^0.0.15`, `@orkestrel/contract` `^0.0.19` | |
71
71
  | `@orkestrel/pool` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
72
72
  | `@orkestrel/probe` | `0.0.24` | L5 | `@orkestrel/lsp` `^0.0.11`, `@orkestrel/mcp` `^0.0.39`, `@orkestrel/pool` `^0.0.17`, `@orkestrel/tool` `^0.0.19`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/timeout` `^0.0.13`, `@orkestrel/contract` `^0.0.19` | `vitest` `^4.1.12`, `typescript` `^6.0.3` |
73
73
  | `@orkestrel/process` | `0.0.15` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
@@ -78,17 +78,17 @@ so network-controlled descriptions never enter agent instruction context.
78
78
  | `@orkestrel/reason` | `0.0.13` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
79
79
  | `@orkestrel/relation` | `0.0.16` | L3 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.18` | |
80
80
  | `@orkestrel/router` | `0.0.17` | L2 | `@orkestrel/abort` `^0.0.13`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
81
- | `@orkestrel/scaffold` | `0.0.103` | L3 | `@orkestrel/console` `^0.0.16`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/process` `^0.0.15`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/markdown` `^0.0.17`, `@orkestrel/template` `^0.0.10` | |
81
+ | `@orkestrel/scaffold` | `0.0.104` | L3 | `@orkestrel/console` `^0.0.16`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/process` `^0.0.15`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/markdown` `^0.0.17`, `@orkestrel/template` `^0.0.10` | |
82
82
  | `@orkestrel/sea` | `0.0.19` | L3 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/process` `^0.0.15`, `@orkestrel/contract` `^0.0.19` | |
83
83
  | `@orkestrel/server` | `0.0.23` | L3 | `@orkestrel/abort` `^0.0.13`, `@orkestrel/codec` `^0.0.6`, `@orkestrel/router` `^0.0.17`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/timeout` `^0.0.13`, `@orkestrel/contract` `^0.0.19` | |
84
84
  | `@orkestrel/sqlite` | `0.0.14` | L1 | `@orkestrel/contract` `^0.0.19` | |
85
85
  | `@orkestrel/sse` | `0.0.10` | L1 | `@orkestrel/contract` `^0.0.19` | |
86
- | `@orkestrel/study` | `0.0.1` | L7 | `@orkestrel/tool` `^0.0.19`, `@orkestrel/abort` `^0.0.13`, `@orkestrel/agent` `^0.0.31`, `@orkestrel/budget` `^0.0.14`, `@orkestrel/ollama` `^0.0.24`, `@orkestrel/timeout` `^0.0.13`, `@orkestrel/contract` `^0.0.19` | |
86
+ | `@orkestrel/study` | `0.0.3` | L7 | `@orkestrel/tool` `^0.0.19`, `@orkestrel/abort` `^0.0.13`, `@orkestrel/agent` `^0.0.31`, `@orkestrel/budget` `^0.0.14`, `@orkestrel/ollama` `^0.0.25`, `@orkestrel/timeout` `^0.0.13`, `@orkestrel/contract` `^0.0.19` | |
87
87
  | `@orkestrel/supervisor` | `0.0.1` | L5 | `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.9`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/workflow` `^0.0.12` | |
88
- | `@orkestrel/table` | `0.0.11` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
88
+ | `@orkestrel/table` | `0.0.12` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
89
89
  | `@orkestrel/template` | `0.0.10` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
90
90
  | `@orkestrel/terminal` | `0.0.20` | L3 | `@orkestrel/sse` `^0.0.10`, `@orkestrel/form` `^0.0.12`, `@orkestrel/console` `^0.0.16`, `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.18` | |
91
- | `@orkestrel/test` | `0.0.28` | L1 | `@orkestrel/contract` `^0.0.19` | `vitest` `^4.1.11`, `playwright` `^1.64.1` |
91
+ | `@orkestrel/test` | `0.0.29` | L1 | `@orkestrel/contract` `^0.0.19` | `vitest` `^4.1.12`, `playwright` `^1.64.1` |
92
92
  | `@orkestrel/timeout` | `0.0.13` | L1 | `@orkestrel/contract` `^0.0.19` | |
93
93
  | `@orkestrel/tool` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
94
94
  | `@orkestrel/toolbox` | `0.0.20` | L6 | `@orkestrel/form` `^0.0.12`, `@orkestrel/tool` `^0.0.19`, `@orkestrel/agent` `^0.0.31`, `@orkestrel/server` `^0.0.23`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.18`, `@orkestrel/relation` `^0.0.16`, `@orkestrel/terminal` `^0.0.20`, `@orkestrel/workflow` `^0.0.23`, `@orkestrel/workspace` `^0.0.12` | |
@@ -8,7 +8,7 @@ permissionMode: default
8
8
  omitClaudeMd: true
9
9
  ---
10
10
 
11
- On Claude Haiku 5.5, you run gates and report their true result. You never edit a file and never fix a failure.
11
+ On Claude Haiku 5.5, you run gates and report their true result. You never edit source or fix a failure. As the runner under `.agents/skills/orkestrel-parallel/SKILL.md`, you create and update only your own coordination log, run artifacts, and result files within the round's assigned `coord/` directory.
12
12
 
13
13
  ## Do
14
14
 
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: orkestrel-parallel
3
+ description: >-
4
+ Run several writer lanes in one checkout at the same time, coordinated by messages: writers edit owned regions in phases, one runner lane owns every test and check process, and the Orchestrator rules and mediates. Use when a campaign has three or more units whose files are mostly disjoint and whose shared files are a few kind files, guides, or entry tests. Do not use it when two units rewrite the same region, when a unit needs a quiet tree for a measurement, or when the harness gives lanes no shared file system or no message channel that wakes an idle lane.
5
+ ---
6
+
7
+ # Load the canonical workflow
8
+
9
+ Read `.agents/skills/orkestrel-parallel/SKILL.md` completely, then read every reference it requires. Follow that canonical workflow before acting.
10
+
11
+ This bridge contains no independent process. `AGENTS.md`, applicable rules, the canonical skill, and the governing guide/spec remain authoritative in that order.
@@ -4,7 +4,9 @@ model = "gpt-6-luna"
4
4
  model_reasoning_effort = "medium"
5
5
  sandbox_mode = "workspace-write"
6
6
  developer_instructions = """
7
- Run gates and report their true result. Never edit a file or fix a failure.
7
+ Run gates and report their true result. Never edit source or fix a failure. As the runner under
8
+ .agents/skills/orkestrel-parallel/SKILL.md, create and update only your own coordination log, run
9
+ artifacts, and result files within the round's assigned coord/ directory.
8
10
 
9
11
  Run exactly the commands the dispatch names, in order. Default scoped sweep: the check: and test:
10
12
  scripts of each named project. Default tree-wide sweep, only when the dispatch says tree-wide: