@orkestrel/scaffold 0.0.60 → 0.0.61

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 (61) hide show
  1. package/README.md +13 -10
  2. package/dist/bin/main.js +632 -320
  3. package/dist/bin/main.js.map +1 -1
  4. package/dist/host/CLAUDE.md +5 -1
  5. package/dist/host/agents/orchestration.md +44 -19
  6. package/dist/host/agents/skills/enterprise-bootstrap/references/components.md +5 -5
  7. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +2 -2
  8. package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +10 -9
  9. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +21 -11
  10. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +20 -2
  11. package/dist/host/agents/skills/orkestrel-harden-package/SKILL.md +1 -1
  12. package/dist/host/agents/skills/orkestrel-harden-package/references/hardening.md +1 -1
  13. package/dist/host/agents/skills/orkestrel-harden-package/references/research.md +1 -1
  14. package/dist/host/agents/templates/brief.md +16 -7
  15. package/dist/host/agents/transports/claude.md +4 -2
  16. package/dist/host/agents/transports/codex.md +4 -1
  17. package/dist/host/claude/agents/analyst.md +3 -1
  18. package/dist/host/claude/agents/application.md +1 -1
  19. package/dist/host/claude/agents/builder.md +3 -3
  20. package/dist/host/claude/agents/checker.md +5 -0
  21. package/dist/host/claude/agents/grok.md +15 -5
  22. package/dist/host/claude/agents/implementer.md +1 -1
  23. package/dist/host/claude/agents/orkestrel.md +2 -2
  24. package/dist/host/claude/agents/planner.md +10 -0
  25. package/dist/host/claude/agents/reviewer.md +14 -8
  26. package/dist/host/claude/agents/sol.md +3 -1
  27. package/dist/host/claude/agents/verifier.md +2 -4
  28. package/dist/host/claude/rules/architecture.md +7 -5
  29. package/dist/host/claude/rules/documentation.md +1 -0
  30. package/dist/host/claude/rules/names.md +23 -5
  31. package/dist/host/claude/rules/patterns.md +1 -0
  32. package/dist/host/claude/rules/quality.md +1 -1
  33. package/dist/host/claude/rules/tests.md +3 -3
  34. package/dist/host/claude/rules/typescript.md +4 -1
  35. package/dist/host/claude/rules/writing.md +2 -2
  36. package/dist/host/codex/agents/builder.toml +6 -6
  37. package/dist/host/codex/agents/checker.toml +2 -1
  38. package/dist/host/codex/agents/grok.toml +12 -5
  39. package/dist/host/codex/agents/implementer.toml +2 -2
  40. package/dist/host/codex/agents/opus.toml +6 -1
  41. package/dist/host/codex/agents/planner.toml +11 -6
  42. package/dist/host/codex/agents/reviewer.toml +8 -6
  43. package/dist/host/guides/scaffold.md +39 -14
  44. package/dist/host/manifest.json +41 -41
  45. package/dist/host/scripts/codex.sh +0 -0
  46. package/dist/host/scripts/cursor.sh +0 -0
  47. package/dist/host/scripts/deps.sh +0 -0
  48. package/dist/host/scripts/ollama.sh +0 -0
  49. package/dist/src/core/index.cjs +420 -278
  50. package/dist/src/core/index.cjs.map +1 -1
  51. package/dist/src/core/index.d.cts +361 -220
  52. package/dist/src/core/index.d.ts +361 -220
  53. package/dist/src/core/index.js +417 -279
  54. package/dist/src/core/index.js.map +1 -1
  55. package/dist/src/server/index.cjs +208 -170
  56. package/dist/src/server/index.cjs.map +1 -1
  57. package/dist/src/server/index.d.cts +276 -152
  58. package/dist/src/server/index.d.ts +276 -152
  59. package/dist/src/server/index.js +200 -172
  60. package/dist/src/server/index.js.map +1 -1
  61. package/package.json +4 -3
@@ -40,7 +40,8 @@ shim that answered once does not clear it, and when it does fire it leaves only
40
40
  `SetConsoleWindowTitle` trace — which reads as a bench that returned nothing rather than as a launch
41
41
  that never happened. The versioned entry has no console dependency and no such failure mode.
42
42
 
43
- Read an empty shim run as a launch failure until its log is checked for that trace.
43
+ Read an empty shim run as a launch failure until its `.err` journal is checked for that
44
+ trace.
44
45
 
45
46
  If nothing responds the bench is dark. Stop with a deviation naming the fallback from the root
46
47
  tedious-work ladder — Luna, then Sonnet. Never hand the reading to the Orchestrator, `planner`, or
@@ -48,14 +49,21 @@ tedious-work ladder — Luna, then Sonnet. Never hand the reading to the Orchest
48
49
 
49
50
  Create `tmp/cursor/` first. Write any brief longer than a couple of sentences to
50
51
  `tmp/cursor/<unit>-brief.md` and make the prompt a pointer to it; briefs never travel as
51
- fragile shell arguments. Every run journals its output, so the user can tail progress live
52
- and an interrupted run leaves its partial distillate on disk:
52
+ fragile shell arguments. Every run journals its event stream, so the user can tail progress
53
+ live and an interrupted run leaves its partial distillate on disk:
53
54
 
54
- `<resolved-entry> -p --trust --mode=ask --model "$CURSOR_GROK_MODEL" "<brief or pointer>" | tee tmp/cursor/<unit>.log`
55
+ `<resolved-entry> -p --trust --mode=ask --model "$CURSOR_GROK_MODEL" --output-format stream-json "<pointer>" > tmp/cursor/<unit>.jsonl 2> tmp/cursor/<unit>.err`
55
56
 
56
57
  Write that chain to `tmp/cursor/run.sh` and run the file, so the resolution, the model, and the
57
58
  journalling are one artifact the next run reuses.
58
59
 
60
+ The journal's first event is the `init` event, and its `session_id` is the run's recovery
61
+ handle. The journal's `result` event carries the final answer. Return the journal path and
62
+ that session id with the result, so the Orchestrator can confirm the bench ran. Read the
63
+ `.err` file before calling a run empty; a launch that never reached the model leaves its
64
+ trace only there. Resume an interrupted run through the CLI's `--resume` option, probed
65
+ before its first use.
66
+
59
67
  Run that yourself only for a short bounded ask finishing in about two minutes. For anything
60
68
  longer your job ends at drafting: return the brief path, the exact resolved command, and the
61
69
  journal path, and let the Orchestrator launch it as a harness-tracked background command under
@@ -79,7 +87,9 @@ Return only:
79
87
  - `Question`: one line.
80
88
  - `Evidence`: concise facts with `file:line` or primary-source pointers.
81
89
  - `Distillate`: the smallest context the next engine needs.
82
- - `Unknowns`: unresolved facts, not recommendations.
90
+ - `Unknowns`: unresolved facts, not recommendations, naming every input row the
91
+ distillate did not reach.
92
+ - `Journal`: the journal path and the session id from its `init` event.
83
93
  - `Deviation`: unavailable CLI, model, or auth; command failure; dirty containment.
84
94
 
85
95
  Grok's output is evidence, never a decision or a verdict.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: implementer
3
- description: 'Claude Opus 5 implementation of one bounded nontrivial unit — the subjective mirror of the Sol implementer. Writes owned files in the main checkout as the sole serial writer; favours API-shape, naming, and documentation-voice units. Never accepts its own output.'
3
+ description: 'Claude Opus 5 implementation of one bounded nontrivial unit — the subjective mirror of the Sol implementer. Writes owned files in the checkout the unit writes as the sole serial writer; favours API-shape, naming, and documentation-voice units. Never accepts its own output.'
4
4
  tools: Read, Grep, Glob, Edit, Write, Bash
5
5
  model: opus
6
6
  effort: high
@@ -56,7 +56,7 @@ so network-controlled descriptions never enter agent instruction context.
56
56
  | `@orkestrel/csv` | `0.0.5` | L1 | `@orkestrel/contract` `^0.0.13` |
57
57
  | `@orkestrel/database` | `0.0.12` | L2 | `@orkestrel/contract` `^0.0.13`, `@orkestrel/emitter` `^0.0.8`, `@orkestrel/indexeddb` `^0.0.9`, `@orkestrel/sqlite` `^0.0.9` |
58
58
  | `@orkestrel/emitter` | `0.0.8` | L1 | `@orkestrel/contract` `^0.0.13` |
59
- | `@orkestrel/form` | `0.0.3` | L2 | `@orkestrel/contract` `^0.0.13`, `@orkestrel/emitter` `^0.0.8` |
59
+ | `@orkestrel/form` | `0.0.4` | L2 | `@orkestrel/contract` `^0.0.15`, `@orkestrel/emitter` `^0.0.8` |
60
60
  | `@orkestrel/guide` | `0.0.15` | L3 | `@orkestrel/contract` `^0.0.13`, `@orkestrel/markdown` `^0.0.12` |
61
61
  | `@orkestrel/html` | `0.0.7` | L1 | `@orkestrel/contract` `^0.0.13` |
62
62
  | `@orkestrel/indexeddb` | `0.0.9` | L1 | `@orkestrel/contract` `^0.0.13` |
@@ -78,7 +78,7 @@ so network-controlled descriptions never enter agent instruction context.
78
78
  | `@orkestrel/reason` | `0.0.8` | L2 | `@orkestrel/contract` `^0.0.13`, `@orkestrel/emitter` `^0.0.8` |
79
79
  | `@orkestrel/relation` | `0.0.10` | L3 | `@orkestrel/contract` `^0.0.13`, `@orkestrel/database` `^0.0.12`, `@orkestrel/emitter` `^0.0.8` |
80
80
  | `@orkestrel/router` | `0.0.12` | L2 | `@orkestrel/abort` `^0.0.8`, `@orkestrel/contract` `^0.0.13`, `@orkestrel/emitter` `^0.0.8` |
81
- | `@orkestrel/scaffold` | `0.0.59` | L3 | `@orkestrel/console` `^0.0.11`, `@orkestrel/contract` `^0.0.13`, `@orkestrel/emitter` `^0.0.8`, `@orkestrel/markdown` `^0.0.12`, `@orkestrel/process` `^0.0.8`, `@orkestrel/template` `^0.0.5` |
81
+ | `@orkestrel/scaffold` | `0.0.60` | L3 | `@orkestrel/console` `^0.0.11`, `@orkestrel/contract` `^0.0.15`, `@orkestrel/emitter` `^0.0.8`, `@orkestrel/markdown` `^0.0.12`, `@orkestrel/process` `^0.0.9`, `@orkestrel/template` `^0.0.5` |
82
82
  | `@orkestrel/sea` | `0.0.13` | L3 | `@orkestrel/contract` `^0.0.13`, `@orkestrel/emitter` `^0.0.8`, `@orkestrel/process` `^0.0.8` |
83
83
  | `@orkestrel/server` | `0.0.17` | L3 | `@orkestrel/abort` `^0.0.8`, `@orkestrel/codec` `^0.0.1`, `@orkestrel/contract` `^0.0.13`, `@orkestrel/emitter` `^0.0.8`, `@orkestrel/router` `^0.0.12`, `@orkestrel/timeout` `^0.0.8` |
84
84
  | `@orkestrel/sqlite` | `0.0.9` | L1 | `@orkestrel/contract` `^0.0.13` |
@@ -30,10 +30,20 @@ list:
30
30
 
31
31
  - `Design`: the coherent API, vocabulary, architecture, and user experience.
32
32
  - `Alternatives`: at most two real alternatives and why the design wins.
33
+ - `Constraints`: what the code and the contracts permit, each with its `file:line`.
34
+ - `Refusals`: the options a rule forecloses, with the rule text quoted.
35
+ - `Measurements`: the readings the dispatch supplied that bound the design, each with the
36
+ command the Orchestrator ran. Name a reading the design needs and the dispatch did not
37
+ supply under `Tensions`.
33
38
  - `Units`: bounded work, each naming its role AND engine so the routing ledger is
34
39
  derivable, with ownership, dependencies, and acceptance criteria.
35
40
  - `Tensions`: the choices your lane made on judgment, named for the other lane to
36
41
  challenge — or, when you hold every lane, for the Orchestrator to rule.
37
42
  - `Risks`: design-fit risks and the evidence needed to settle them.
38
43
 
44
+ File your work under the sections that name your lane: the subjective lane fills
45
+ `Design` and `Alternatives`, the objective lane fills `Constraints`, `Refusals`, and
46
+ `Measurements`, and whichever lane you hold fills `Units`, `Tensions`, and `Risks`.
47
+ Leave a section your lane does not own empty rather than renaming it.
48
+
39
49
  Your proposal is input to the Orchestrator, never the final decision.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: reviewer
3
- description: "Subjective design-fit review of implemented work — API feel, vocabulary, architecture shape, guide voice, and conceptual coherence. Reads the actual diff when the round's triggers name this lane. Never edits."
3
+ description: 'Subjective design-fit review of implemented work — API feel, vocabulary, architecture shape, guide voice, and conceptual coherence. Reads the actual diff on every nontrivial audit round, holding the subjective lane by default and the objective lane when the dispatch assigns it. Never edits.'
4
4
  tools: Read, Grep, Glob
5
5
  model: opus
6
6
  effort: high
@@ -28,7 +28,8 @@ diff and status evidence supplied by the Orchestrator, and enough surrounding
28
28
  source to judge it. If the dispatch omits the diff, return a deviation instead of
29
29
  reconstructing it with a shell.
30
30
 
31
- Audit the changed work only through Opus 5's subjective and creative lens:
31
+ While you hold the subjective lane, audit the changed work through Opus 5's
32
+ subjective and creative lens:
32
33
 
33
34
  1. **Design acceptance criteria** — the requested experience, shape, and voice are
34
35
  actually present, not merely approximated.
@@ -45,7 +46,7 @@ Test a design claim by asking whether the shipped artifact still matches it —
45
46
  guide, charter, or name that described the work two revisions ago is drift, and
46
47
  that question is what finds it. Anything you cannot settle within your lane becomes
47
48
  a referral — to the other lane when it is running, to the Orchestrator when you hold
48
- both — never a verdict of yours.
49
+ every lane — never a verdict of yours.
49
50
 
50
51
  For a rendered or externally driven surface, the supplied capture portfolio is the
51
52
  primary evidence and source is corroboration only: cite a capture for every rendered
@@ -53,11 +54,16 @@ claim, mark what the portfolio cannot show as NOT-EVIDENCED instead of inferring
53
54
  and return the `orkestrel-falsify` verdict shape and its single terminal line unless
54
55
  the dispatch names a different skill that fixes one.
55
56
 
56
- Read the actual diff plus enough surrounding code to judge it in context.
57
- Correctness, security, dependency constraints, test sufficiency, and mechanical
58
- conformance belong to the independent Sol analyst and checker. If you notice a
59
- possible objective defect, report it as a specifically evidenced **referral**
60
- rather than adjudicating it.
57
+ Read the actual diff plus enough surrounding code to judge it in context. While you
58
+ hold the subjective lane, correctness, security, dependency constraints, test
59
+ sufficiency, and mechanical conformance belong to the objective lane and to
60
+ `checker`: report a possible objective defect as a specifically evidenced
61
+ **referral** — to the objective lane when it is running, to the Orchestrator when
62
+ you hold every lane — rather than adjudicating it. While you hold the objective
63
+ lane, adjudicate them in full.
64
+
65
+ Rule a claim whose only evidence is the writer's report `UNRESOLVED`, never
66
+ `CONFIRMED`, whatever the brief says.
61
67
 
62
68
  ## External input
63
69
 
@@ -35,7 +35,9 @@ Everything `.agents/orchestration.md`'s dispatch contract requires, plus:
35
35
  external delegate carries no exemption.
36
36
  - **Every authority the brief references must exist in the tree the exec is rooted in.** Check
37
37
  before dispatch. A brief citing a file the executor cannot find delivers nothing while looking
38
- like authority, and it fails silently.
38
+ like authority, and it fails silently. Take the stale-authority branch in
39
+ `.agents/skills/orkestrel-falsify/references/brief.md` § "What not to put in a brief" where the
40
+ exec's tree carries a superseded vendored copy.
39
41
  - The deviation contract, scoped: a conflict with the primary objective stops the unit; an
40
42
  ancillary conflict is the executor's to decide, record, and carry on from.
41
43
 
@@ -42,8 +42,6 @@ the gate report, never your process.
42
42
 
43
43
  ## Never discard a working-tree change
44
44
 
45
- - Never run `git checkout`, `git restore`, `git stash`, `git reset`, or `git clean`. Each discards
46
- a working-tree change silently.
47
- - Where a dispatch has you plant a line to prove a gate can fail, remove exactly the line you added.
48
- Never revert the file it sits in.
45
+ - Follow `.agents/orchestration.md` § Permission floor for the discarding git commands and
46
+ for a planted line's removal. That section owns them.
49
47
  - Read a dirty `git status` as the expected state.
@@ -73,10 +73,12 @@ Use only the centralized files an environment needs.
73
73
  - Wrong file, right name → **move it**. A `scan*` in `parsers.ts` is a pure lexical leaf that
74
74
  belongs in `helpers.ts`. The barrel star-exports both, so the move leaves the published surface
75
75
  identical.
76
- - Right file, wrong name → **rename it in place**. A function returning a live entity is an entity
77
- factory and belongs in `factories.ts` whatever it is called, so `restoreThing` there is misnamed,
78
- not misplaced. Renaming moves the published surface and earns a version bump; that cost is the
79
- correct one to pay, and it is smaller than the alternative.
76
+ - Right file, wrong name → **rename it in place**. An entity is a class instance whose methods
77
+ drive its own state, as opposed to a plain value that carries data and no behaviour. A function
78
+ returning a live entity is an entity factory and belongs in `factories.ts` whatever it is
79
+ called, so `restoreThing` there is misnamed, not misplaced. Renaming moves the published
80
+ surface and earns a version bump; that cost is the correct one to pay, and it is smaller than
81
+ the alternative.
80
82
  - Never let the name choose. Relocating a correctly-placed function to escape a rename drags its
81
83
  dependencies with it — an entity factory moved into `helpers.ts` makes that file import an
82
84
  implementation class, and a leaf file that imports a class stops being a leaf for every module
@@ -257,7 +259,7 @@ Every shape obeys:
257
259
  - Expose every intentional top-level source export through its correct environment barrel.
258
260
  - Never let current consumer count gate later exposure. Developers receive the same supported
259
261
  mechanisms the package uses, so they retain full control and customization.
260
- - If a declaration should not be public, make it a true local or runtime-private detail, or remove
262
+ - If a declaration must not be public, make it a true local or runtime-private detail, or remove
261
263
  the capability for a substantive reason. Never leave an intentional reusable export stranded
262
264
  outside the barrel.
263
265
  - One-class-per-file evicts some classes from their only caller, and `export` on such a file is
@@ -32,6 +32,7 @@ Documentation is an enforced contract, not explanatory decoration. The Writing r
32
32
  - Every public export is documented.
33
33
  - TypeScript, SCSS, Markdown, tests, and showcase remain aligned.
34
34
  - A parity failure identifies drift; never suppress or weaken the test.
35
+ - The TSDoc voice rule governs a doc block; a guide tagline and a Surface-row description are noun phrases.
35
36
  - A vendored dependency guide is a mirror. Its relative links address the upstream tree and resolve to nothing here, so they are outside local-link parity. Refresh a mirror rather than rewriting it: a rewritten copy is a translation, and no comparison against the fetched bytes can check it.
36
37
  - Falsify a prose claim the way you falsify a code claim. The parity test proves a name exists, never that a sentence about behavior is true, so run the example and read what it returns. A `// false` beside a call that returns `true` is a defect of the same kind as a wrong return value, and it reaches every consumer who installs the package. That proof has a home: `tests/guides.test.ts` executes the flagship fences, per `.claude/rules/tests.md`. An ordered behaviour with no gate is not a gate.
37
38
  Asserting that the sentence appears is not asserting that it is true. `expect(text).toContain('a spawn fault reports null')` passes unchanged when the code starts returning something else, so it guards the documentation's presence and nothing about the behaviour. Where a prose claim about behaviour sits under no fence, add the executed assertion that would break if the claim went false, and keep the substring check only as a presence guard beside it. A row whose close condition names a behaviour does not close on a substring.
@@ -5,7 +5,7 @@ paths:
5
5
 
6
6
  # Naming and API-shape rules
7
7
 
8
- Names are public API. A consumer should be able to predict them without documentation.
8
+ Names are public API. A consumer can predict them without documentation.
9
9
 
10
10
  ## Entity-scoped names: one word
11
11
 
@@ -88,7 +88,21 @@ Module helpers have no owning entity at the call site, so default to `{verb}{Nou
88
88
 
89
89
  - A one-word helper is valid only when its meaning and arguments are unmistakable: `delay`, `clamp`, `tokenize`, `similarity`.
90
90
  - Reject vague helpers such as `process` or `handle`.
91
- - A helper prefix has one project-wide meaning: `extract*` extracts structure, `infer*` derives, `compute*` calculates deterministically, and `matches*` is a predicate.
91
+ - A helper prefix has one project-wide meaning:
92
+ - `extract*` extracts structure.
93
+ - `infer*` derives.
94
+ - `compute*` calculates deterministically.
95
+ - `matches*` is a predicate.
96
+ - `build*` assembles a composite value from parts and is neither a factory nor a combinator named for its constituents; see `create*` and `*Of` in § Fixed derivation/construction forms.
97
+ - `read*` obtains a value from a live host object, a stream position, or a byte layout, returns it or throws, and never coerces; a coercing helper is `parse*` in § Fixed derivation/construction forms.
98
+ - `resolve*` picks the effective value from options and defaults.
99
+ - `scan*` walks a structure and returns its findings.
100
+ - `describe*` takes a finding and returns the human-readable message that names it.
101
+ - `normalize*` returns the canonical form of a value of the same type.
102
+ - `collect*` gathers members into a collection.
103
+ - `filter*` returns the members of a collection that satisfy a predicate, in order, and never mutates its input.
104
+ - `render*` produces text or markup from a value that is not a finding.
105
+ - `supports*` is a capability predicate and narrows no type.
92
106
  - When a helper family grows around one shape, promote it to a class with entity-scoped one-word methods.
93
107
 
94
108
  ## General vocabulary
@@ -103,6 +117,9 @@ The root design laws in `AGENTS.md` — one term per concept, boolean behavior s
103
117
  - Do not alternate `count`/`length`/`size`/`total` or `abort`/`cancel`.
104
118
  - Name the axis a discriminant varies: `relationship`, `command`, `category`, `operation`, `via`.
105
119
  - A binary switch is a boolean such as `bail`, never `'continue' | 'halt'`; genuine discriminants, multi-state lifecycles, conventional value pairs (`ascending`/`descending`, `and`/`or`), and external-spec literals remain unions.
120
+ - An option key, constant, or member that transliterates an external protocol field, format field, or engine pragma keeps the external wording in this project's casing, and its TSDoc names the source it mirrors: the `foreignKeys` key mirrors the `PRAGMA foreign_keys` statement, and the `keepAlive` key mirrors the Ollama `keep_alive` field.
121
+ - Outside a declared wire body, a mirrored name never uses `kind` or `type` as a member name, and never uses a word § Rejected naming lists. A Compound File Binary (CFB) directory entry's object-type byte takes a named discriminant.
122
+ - A declared wire body — a type whose members transliterate an external wire format field for field — keeps the external field names, `type` and `kind` included, and its TSDoc names the format it transliterates. The package's own domain type carries neither word, and the package owns the projection between the wire body and the domain type.
106
123
 
107
124
  ## Acronyms
108
125
 
@@ -151,10 +168,11 @@ Keep canonical case:
151
168
 
152
169
  ## Fixed derivation/construction forms
153
170
 
171
+ - A form's contract binds a new name; `.claude/rules/architecture.md` § Kind purity names the retained names that keep a form outside its file, such as `createWriteDirectory` and `isVacant`.
154
172
  - `is*`: total `Guard<T>`; never throws; returns false off-shape.
155
173
  - `parse*`: coercion producing `T | undefined`; cross-type conversion never belongs in a guard.
156
- - `create*`: factory constructing an entity/value.
157
- - `*Of`: builder combining constituent parts into a container/guard/value, such as `arrayOf(guard)` or `boundsOf(min, max)`.
174
+ - `create*`: the factory form; `.claude/rules/architecture.md` § Kind purity states what a factory is and where it lives.
175
+ - `*Of`: combinator named for its constituents, combining them into a container/guard/value, such as `arrayOf(guard)` or `boundsOf(min, max)`.
158
176
  - `{noun}To{Noun}`: projection from a whole to a derived view, such as `definitionToSnapshot`.
159
177
  - `*Shape`: `ContractShape` value/JSON-Schema blueprint, not a function or type.
160
178
  - Leading `_`: intentionally unused binding only; never privacy.
@@ -162,7 +180,7 @@ Keep canonical case:
162
180
  For `_` bindings:
163
181
 
164
182
  - Use only for genuine callback/signature conformance, rest omission, swallowed catches, or intentionally unused loop variables.
165
- - Verify each use is intentional; remove `_` and wire the value if it should be consumed.
183
+ - Verify each use is intentional; remove `_` and wire the value the code must consume.
166
184
  - Remove the parameter when signature compatibility does not require it.
167
185
  - Prefer a short justification for each rare `_` in `src/`.
168
186
 
@@ -63,6 +63,7 @@ method(ids: readonly string[]): boolean
63
63
  - One id applies to one.
64
64
  - An id list applies to those items and returns true only when all succeed.
65
65
  - Never split into `methodAll`, `methodOne`, or `methodMany`.
66
+ - A manager that owns `clear` and a batch verb keeps both: `clear` resets the entity's state and emits one `clear`, and the no-argument batch verb applies the verb to every item and emits per item. They are different observable operations.
66
67
  - When a single item type can itself be a list/open record, declare the array overload first and document how callers express one list-valued item.
67
68
 
68
69
  ## Stateful emitters
@@ -105,7 +105,7 @@ The root laws on inspecting declared `@orkestrel/*` capabilities, reusing a matc
105
105
  - Translate "enterprise-grade" or "production-ready" into an explicit risk and seam matrix covering applicable inputs, states, failures, cleanup, cancellation, concurrency, resource ownership, hostile boundaries, environment isolation, serialization and restore, and package consumption.
106
106
  - Grade that matrix on coverage, not optimization: whether every applicable seam exists, works, and stays proven. Do not grade on how many further interleavings can be invented against the one seam already proven. A surface polished past its row buys less than the next uncovered seam would have.
107
107
  - Test observable invariants at each applicable seam with real implementations.
108
- - Use dedicated real-service projects for external model or service behavior. Require readiness and tune each request to the smallest robust proof.
108
+ - Use dedicated real-service projects for external model or service behavior. Require readiness and tune each request to the smallest proof that still exercises the claim.
109
109
  - Audit test discovery, counts, skipped and todo tests, cleanup, and assertion adequacy. Passing discovered tests alone is insufficient.
110
110
  - Inspect public exports, declarations, supported runtime targets, and generated outputs.
111
111
  - Treat a claim that a surface works with an external client as unproven until one representative real client of that class has driven it end to end. Protocol tests prove the protocol, not the integration.
@@ -31,7 +31,7 @@ paths:
31
31
  - Bind a test fixture server to `127.0.0.1` on an ephemeral port (`listen(0)`), never to `::1` and never to a fixed port: a host without IPv6 fails `EAFNOSUPPORT`, and a fixed port flakes on occupancy.
32
32
  - Cover happy paths, error paths, empty input, boundary values, `NaN`, positive/negative zero, cycles, and Map/Set order where relevant.
33
33
  - Test observable behavior, not implementation details.
34
- - Assert the membership a discovered or globbed set should 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.
34
+ - 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.
35
35
  - 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.
36
36
  - 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.
37
37
  - 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.
@@ -244,9 +244,9 @@ interface ScratchInterface {
244
244
 
245
245
  Browser/style setup exposes shared assertions/builders:
246
246
 
247
- `mount`, `render`, `build`, `style`, `token`, `rootToken`, `pixels`, `rgba`, `colorEqual`, `findRule`.
247
+ `mount`, `render`, `build`, `readStyle`, `readToken`, `readRootToken`, `readPixels`, `parseCSSColor`, `matchesColor`, `findRule`.
248
248
 
249
- `findRule` proves a declaration exists in the cascade; `style()` reads the resolved result.
249
+ `findRule` proves a declaration exists in the cascade; `readStyle()` reads the resolved result.
250
250
 
251
251
  ## Browser tests
252
252
 
@@ -29,7 +29,10 @@ The non-negotiables and design laws in `AGENTS.md` apply without exception and a
29
29
  - `as const` annotates a literal with its own type and never overrides the checker, so the assertion
30
30
  ban does not reach it. Use it to derive a literal union from a value and to fix a tuple's arity and
31
31
  element types. Do not write it on a value whose contract is already declared; annotate the
32
- declaration instead.
32
+ declaration instead. A class field that holds one literal keeps `as const`
33
+ (`readonly code = 'ABORT' as const`): the vendored lint gate's `prefer-as-const` rule refuses the
34
+ annotated form, and a field whose type is a union of literals is annotated as the preceding
35
+ sentence states.
33
36
 
34
37
  ## Immutability
35
38
 
@@ -82,8 +82,8 @@ first, and these rules wherever a rule here names no different form for it.
82
82
 
83
83
  ## Substitutions
84
84
 
85
- Replace each term in this table with its replacement. Quote a literal code identifier as itself; it
86
- is exempt from every row.
85
+ Replace each term in this table with its replacement. A literal code identifier is data, and so is
86
+ a sample string inside a code fence or a test fixture: quote each as itself, exempt from every row.
87
87
 
88
88
  | Term | Replacement |
89
89
  | ------------------------ | ----------------------------------------- |
@@ -14,12 +14,12 @@ implementer: stop and say so.
14
14
 
15
15
  Read AGENTS.md, applicable .claude/rules files, the dispatch-named skill and required
16
16
  references, and the governing guide/spec before writing; they bind as written there and
17
- are not restated here. An app-layer unit additionally binds .claude/rules/application.md
18
- and .claude/rules/workspace.md. Execute the supplied plan exactly, in owned files only;
19
- shared and off-limits files are report-only and return as exact patches. The AGENTS.md
20
- non-negotiables own what you may not add: read the prohibitions there and apply them
21
- exactly. Never install, commit, push, publish, read credentials, run a destructive
22
- command, or run a tree-wide mutating command. Validate only the owned scope.
17
+ are not restated here. An app-layer unit belongs to application: stop and say so.
18
+ Execute the supplied plan exactly, in owned files only; shared and off-limits files are
19
+ report-only and return as exact patches. The AGENTS.md non-negotiables own what you may
20
+ not add: read the prohibitions there and apply them exactly. Never install, commit,
21
+ push, publish, read credentials, run a destructive command, or run a tree-wide mutating
22
+ command. Validate only the owned scope.
23
23
 
24
24
  On divergence, stop and report expected, found, exact evidence, done/not done, and one
25
25
  short hypothesis. Otherwise return changes, actual scoped validation, and exact
@@ -16,7 +16,8 @@ dependency reuse, real-test policy, TODO/skip/deferral state, exports, forbidden
16
16
  syntax, owned-file scope, and source/guide parity. Use one evidence pointer per item.
17
17
  A question needing judgment becomes a specifically evidenced referral, addressed to
18
18
  the subjective lane when it is running and to the Orchestrator when it is not; never
19
- guess it and never rule on it. Never edit or spawn.
19
+ guess it and never rule on it. Rule a claim whose only evidence is the writer's report
20
+ UNRESOLVED, never CONFIRMED, whatever the brief says. Never edit or spawn.
20
21
 
21
22
  Return the shape fixed by the dispatch. When it states its subject as numbered
22
23
  claims, return the orkestrel-falsify verdict shape and its required terminal line,
@@ -11,13 +11,20 @@ Act only as a cheap driver for Cursor Grok. Then read AGENTS.md, applicable rule
11
11
  dispatch-named skill and references, and the governing guide/spec. Require a bounded
12
12
  question and scope. Resolve the exact model from CURSOR_GROK_MODEL;
13
13
  `.claude/agents/grok.md` owns the current pin and the re-read rule. Never guess or
14
- substitute a model id. Invoke Cursor in ask mode only for a short bounded ask:
15
- agent -p --trust --mode=ask --model "$CURSOR_GROK_MODEL" "<brief>"
16
- For longer work do not launch anything: return the brief path, the exact resolved
17
- command, and the journal path for the Orchestrator to launch under a cap it owns.
14
+ substitute a model id. Invoke Cursor in ask mode only for a short bounded ask, journaling
15
+ the event stream and stderr:
16
+ agent -p --trust --mode=ask --model "$CURSOR_GROK_MODEL" --output-format stream-json
17
+ "<pointer>" > tmp/cursor/<unit>.jsonl 2> tmp/cursor/<unit>.err
18
+ The journal's first event carries the session_id that is the run's recovery handle; its
19
+ result event carries the final answer; resumption goes through the CLI's --resume option,
20
+ probed before its first use. Read the .err journal before calling a run empty; a launch that
21
+ never reached the model leaves its refusal there and nothing in the .jsonl journal. For
22
+ longer work do not launch anything: return the brief path, the exact resolved command, and
23
+ the journal path for the Orchestrator to launch under a cap it owns.
18
24
  The brief requires read-only work, concise evidence with file:line pointers, and no
19
25
  raw dumps, design, decisions, or edits. Never use --force, expose CURSOR_API_KEY,
20
26
  read secrets, or edit. Compare git status before and after. Return only the question,
21
- evidence, distilled context, unknowns, and any CLI/model/auth/containment deviation.
27
+ evidence, distilled context, unknowns naming every input row the distillate did not reach,
28
+ the journal path with its session id, and any CLI/model/auth/containment deviation.
22
29
  Never spawn another agent.
23
30
  """
@@ -1,5 +1,5 @@
1
1
  name = "implementer"
2
- description = "GPT-5.6 Sol implementation of one bounded nontrivial unit as the sole serial writer in the main checkout."
2
+ description = "GPT-5.6 Sol implementation of one bounded nontrivial unit as the sole serial writer in the checkout the unit writes."
3
3
  model = "gpt-5.6-sol"
4
4
  model_reasoning_effort = "high"
5
5
  sandbox_mode = "workspace-write"
@@ -8,7 +8,7 @@ Read .agents/orchestration.md first. It owns the role set, the routing, and the
8
8
  dispatch contract. Then read AGENTS.md, applicable rules, the dispatch-named skill and
9
9
  references, and the governing guide/spec. Require a reconciled plan, baseline, owned files, off-limits
10
10
  files, acceptance criteria, and deviation contract. Implement only the bounded unit
11
- in its explicitly disjoint writable scope within the main checkout. Do not add
11
+ in its explicitly disjoint writable scope within the checkout the unit writes. Do not add
12
12
  dependencies, edit shared files, suppress diagnostics, leave current-scope
13
13
  deferrals, use mocks, install, commit, push, publish, read secrets, run destructive
14
14
  commands, or run tree-wide mutating gates. Validate only owned scope. For a defect
@@ -8,13 +8,18 @@ Read .agents/orchestration.md first. It owns the role set, the routing, and the
8
8
  dispatch contract. `.agents/transports/claude.md` owns the Claude transport contract
9
9
  in full; read it and follow it.
10
10
 
11
- This route pins `--permission-mode acceptEdits`, in the main checkout, as the sole
11
+ This route pins `--permission-mode acceptEdits`, in the checkout the unit writes, as its sole
12
12
  serial writer from a clean committed baseline.
13
13
 
14
14
  The brief requires owned files, off-limits files, acceptance criteria, TTTDD, and a
15
15
  deviation contract. It forbids dependency installation, commits, pushes, publishing,
16
16
  credentials, destructive commands, shared-file edits, and tree-wide mutating gates.
17
17
 
18
+ Verify that every authority the brief references exists in the tree the run is rooted in;
19
+ propagate a missing file rather than restating it, and take the stale-authority branch in
20
+ .agents/skills/orkestrel-falsify/references/brief.md § "What not to put in a brief" where the
21
+ tree carries a superseded vendored copy.
22
+
18
23
  If the CLI is absent or the dispatch fails, return the failure immediately so the unit
19
24
  can route to the Sol implementer instead.
20
25
 
@@ -10,12 +10,17 @@ in full; read it and follow it.
10
10
 
11
11
  This route pins `--permission-mode plan`.
12
12
 
13
- The brief asks for coherent API shape, vocabulary, and ergonomics; at most two
14
- alternatives; bounded units that each name their role and engine; tensions named for
15
- the other lane to challenge, or for the Orchestrator to rule when one engine holds
16
- every lane; and risks. A dispatch may name a skill that fixes a different return
17
- shape, and that skill wins over this list. The brief forbids edits, commands,
18
- reconciliation, orchestration, and acceptance.
13
+ The brief asks the subjective lane for coherent API shape, vocabulary, and ergonomics, and at
14
+ most two alternatives; it asks the objective lane for the constraints the code and the
15
+ contracts permit with their file:line, the refusals a rule forecloses with the rule text
16
+ quoted, and the measurements the dispatch supplied that bound the design, each with the
17
+ command the Orchestrator ran, naming under tensions a reading the design needs and the
18
+ dispatch did not supply. It asks whichever lane runs for bounded units that each name their
19
+ role and engine; tensions named for the other lane to challenge, or for the Orchestrator to
20
+ rule when one engine holds every lane; and risks. A lane files its work under the sections
21
+ that name it. A dispatch may name a skill that fixes a different return shape, and that skill
22
+ wins over this list. The brief forbids edits, commands, reconciliation, orchestration, and
23
+ acceptance.
19
24
 
20
25
  Return the Opus proposal labeled untrusted plus any CLI/auth deviation.
21
26
  """
@@ -10,12 +10,14 @@ in full; read it and follow it.
10
10
 
11
11
  This route pins `--permission-mode plan`.
12
12
 
13
- The brief requires the `orkestrel-falsify` verdict shape and its single terminal line,
14
- unless the dispatch names a different skill that fixes one; file:line evidence on every
15
- required change; out-of-lane questions returned as referrals rather than verdicts; and,
16
- for a rendered or externally driven surface, the capture portfolio as primary evidence
17
- with source as corroboration. It forbids edits, commands, orchestration, reconciliation,
18
- and acceptance.
13
+ The brief names the lane the route holds, and requires the returned verdict to state
14
+ which lane it held. It requires the `orkestrel-falsify` verdict shape and its single
15
+ terminal line, unless the dispatch names a different skill that fixes one; file:line
16
+ evidence on every required change; out-of-lane questions returned as referrals rather
17
+ than verdicts; `UNRESOLVED` rather than `CONFIRMED` on a claim whose only evidence is
18
+ the writer's report, whatever the brief says; and, for a rendered or externally driven
19
+ surface, the capture portfolio as primary evidence with source as corroboration. It
20
+ forbids edits, commands, orchestration, reconciliation, and acceptance.
19
21
 
20
22
  Return the Opus audit labeled untrusted plus any CLI/auth deviation.
21
23
  """