@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.
- package/README.md +13 -10
- package/dist/bin/main.js +632 -320
- package/dist/bin/main.js.map +1 -1
- package/dist/host/CLAUDE.md +5 -1
- package/dist/host/agents/orchestration.md +44 -19
- package/dist/host/agents/skills/enterprise-bootstrap/references/components.md +5 -5
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +10 -9
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +21 -11
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +20 -2
- package/dist/host/agents/skills/orkestrel-harden-package/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-harden-package/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-harden-package/references/research.md +1 -1
- package/dist/host/agents/templates/brief.md +16 -7
- package/dist/host/agents/transports/claude.md +4 -2
- package/dist/host/agents/transports/codex.md +4 -1
- package/dist/host/claude/agents/analyst.md +3 -1
- package/dist/host/claude/agents/application.md +1 -1
- package/dist/host/claude/agents/builder.md +3 -3
- package/dist/host/claude/agents/checker.md +5 -0
- package/dist/host/claude/agents/grok.md +15 -5
- package/dist/host/claude/agents/implementer.md +1 -1
- package/dist/host/claude/agents/orkestrel.md +2 -2
- package/dist/host/claude/agents/planner.md +10 -0
- package/dist/host/claude/agents/reviewer.md +14 -8
- package/dist/host/claude/agents/sol.md +3 -1
- package/dist/host/claude/agents/verifier.md +2 -4
- package/dist/host/claude/rules/architecture.md +7 -5
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/names.md +23 -5
- package/dist/host/claude/rules/patterns.md +1 -0
- package/dist/host/claude/rules/quality.md +1 -1
- package/dist/host/claude/rules/tests.md +3 -3
- package/dist/host/claude/rules/typescript.md +4 -1
- package/dist/host/claude/rules/writing.md +2 -2
- package/dist/host/codex/agents/builder.toml +6 -6
- package/dist/host/codex/agents/checker.toml +2 -1
- package/dist/host/codex/agents/grok.toml +12 -5
- package/dist/host/codex/agents/implementer.toml +2 -2
- package/dist/host/codex/agents/opus.toml +6 -1
- package/dist/host/codex/agents/planner.toml +11 -6
- package/dist/host/codex/agents/reviewer.toml +8 -6
- package/dist/host/guides/scaffold.md +39 -14
- package/dist/host/manifest.json +41 -41
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/src/core/index.cjs +420 -278
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +361 -220
- package/dist/src/core/index.d.ts +361 -220
- package/dist/src/core/index.js +417 -279
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +208 -170
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +276 -152
- package/dist/src/server/index.d.ts +276 -152
- package/dist/src/server/index.js +200 -172
- package/dist/src/server/index.js.map +1 -1
- 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
|
|
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
|
|
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" "<
|
|
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
|
|
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.
|
|
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.
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
58
|
-
conformance belong to the
|
|
59
|
-
possible objective defect
|
|
60
|
-
|
|
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
|
-
-
|
|
46
|
-
a
|
|
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**.
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
157
|
-
- `*Of`:
|
|
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
|
|
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
|
|
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
|
|
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`, `
|
|
247
|
+
`mount`, `render`, `build`, `readStyle`, `readToken`, `readRootToken`, `readPixels`, `parseCSSColor`, `matchesColor`, `findRule`.
|
|
248
248
|
|
|
249
|
-
`findRule` proves a declaration exists in the cascade; `
|
|
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.
|
|
86
|
-
|
|
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
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
command
|
|
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.
|
|
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
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
14
|
-
alternatives;
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
and
|
|
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
|
"""
|