@orkestrel/scaffold 0.0.91 → 0.0.92
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/dist/agents/templates/brief.md +2 -0
- package/dist/bin/main.js +3 -3
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +2 -2
- package/dist/host/agents/orchestration.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +3 -3
- package/dist/host/agents/skills/orkestrel-publish/references/window.md +3 -4
- package/dist/host/agents/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/agents/templates/brief.md +2 -0
- package/dist/host/agents/transports/cursor.md +1 -1
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/grok.md +1 -1
- package/dist/host/claude/agents/orkestrel.md +8 -8
- package/dist/host/claude/agents/planner.md +1 -1
- package/dist/host/claude/agents/researcher.md +1 -1
- package/dist/host/claude/agents/scout.md +1 -1
- package/dist/host/claude/rules/names.md +1 -1
- package/dist/host/claude/rules/patterns.md +1 -1
- package/dist/host/claude/rules/quality.md +11 -0
- package/dist/host/claude/rules/tests.md +7 -8
- package/dist/host/claude/rules/writing.md +2 -1
- package/dist/host/codex/agents/researcher.toml +2 -2
- package/dist/host/codex/agents/scout.toml +1 -1
- package/dist/host/guides/browser.md +413 -346
- package/dist/host/guides/pool.md +154 -58
- package/dist/host/manifest.json +23 -23
- package/dist/src/core/index.cjs +3 -3
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +3 -3
- package/dist/src/core/index.js.map +1 -1
- package/package.json +3 -3
package/dist/host/AGENTS.md
CHANGED
|
@@ -82,7 +82,7 @@ A repair inside an existing file is never large by itself. A private retry, cach
|
|
|
82
82
|
Within the size, in order:
|
|
83
83
|
|
|
84
84
|
1. **Types.** Write or revise the contract in `*/types.ts`. Typecheck it.
|
|
85
|
-
2. **Prove.** Select the instrument per `.claude/rules/quality.md` § Instruments: a `prove` claim (edit, test, breaking edit, breaking stage) for a TypeScript claim, otherwise the smallest test or probe. Quote a `prove` closing line where the claim is reported.
|
|
85
|
+
2. **Prove.** Select the instrument per `.claude/rules/quality.md` § Instruments: a `prove` claim (edit, test, breaking edit, breaking stage) for a TypeScript claim, otherwise the smallest test or probe. Quote a `prove` closing line where the claim is reported. When attempts to form a claim stop narrowing the question, write the test and continue.
|
|
86
86
|
3. **Implement.** Conform to the types. Place each declaration in its kind file. Update the barrel.
|
|
87
87
|
4. **Test.** Cover happy paths, edge cases, failures, and boundaries with deterministic tests against real implementations. For a defect, record the failing command and count before the fix and the same command green after.
|
|
88
88
|
5. **Consolidate.** Remove duplication, nested functions, and superfluous wrappers without widening the API.
|
|
@@ -120,7 +120,7 @@ Each row is a normative extension of this file. Its `paths` frontmatter controls
|
|
|
120
120
|
| `.claude/rules/portability.md` | Host branching, paths, line endings, processes, terminals, OS claims |
|
|
121
121
|
| `.claude/rules/documentation.md` | Guides, parity, roadmap, showcase, examples, skill files |
|
|
122
122
|
| `.claude/rules/writing.md` | Prose in guides, replies, commits, and instruction files |
|
|
123
|
-
| `.claude/rules/quality.md` | Evidence, probes, instruments, research, completion
|
|
123
|
+
| `.claude/rules/quality.md` | Evidence, probes, instruments, performance, research, completion |
|
|
124
124
|
|
|
125
125
|
## Writing
|
|
126
126
|
|
|
@@ -58,7 +58,7 @@ The harness's own engine orchestrates: Opus 5.5 in Claude Code, Astra in Codex,
|
|
|
58
58
|
|
|
59
59
|
- Never run a review on a small change. Never run a second design round on the same brief.
|
|
60
60
|
- A fix round re-audits the repaired claim only. A fix that adopted the reviewer's prescription verbatim closes with a mutation probe (disable the load-bearing line, watch the test fail, restore it). A fix that departs from it gets one pass by the other engine.
|
|
61
|
-
-
|
|
61
|
+
- When review rounds at one seam keep surfacing defects without converging on their source, follow `.agents/skills/orkestrel-falsify/SKILL.md` § End the depth search.
|
|
62
62
|
- An all-confirmed round ends the audit. A round needs an added or repaired claim to attack; reviewer appetite is not a subject.
|
|
63
63
|
|
|
64
64
|
## Campaign
|
|
@@ -41,7 +41,7 @@ Write `tmp/units/<unit>-claims.md` and point every lane at it. Read `references/
|
|
|
41
41
|
Every lane returns exactly this:
|
|
42
42
|
|
|
43
43
|
1. Numbered verdicts in claim order, one value each: `CONFIRMED` (attacked and held, with the attack), `BROKEN` (the failing input, state, or interleaving plus the smallest correct fix), `UNRESOLVED` (what would settle it; a claim whose only evidence is the writer's report), `NOT-EVIDENCED` (the capture that is missing).
|
|
44
|
-
2. Findings outside the claims, each substantiated to the `BROKEN` standard.
|
|
44
|
+
2. Findings outside the claims, each substantiated to the `BROKEN` standard. After them, list each cost finding that `.claude/rules/quality.md` § Performance rules advisory, marked `ADVISORY`; an advisory never enters the terminal line.
|
|
45
45
|
3. Attacked and held: attacks no verdict line carries, and the adjacent behavior that looks like the defect and is correct.
|
|
46
46
|
4. One terminal line: `VERDICT: PASS` or `VERDICT: FAIL <claim numbers>; outside the claims: <finding ids or none>`. `PASS` needs every claim `CONFIRMED` and no substantiated outside finding.
|
|
47
47
|
|
|
@@ -62,6 +62,6 @@ Read `references/reconcile.md`.
|
|
|
62
62
|
|
|
63
63
|
Write `.orkestrel/<package>/<unit>-audit-verdict.md` with the lanes that ran, their engines, the per-claim rulings, the findings carried into fix units, and any lane the round did not run with the reason. Delete the claims file and the verdict when the seam closes.
|
|
64
64
|
|
|
65
|
-
##
|
|
65
|
+
## End the depth search
|
|
66
66
|
|
|
67
|
-
|
|
67
|
+
When review rounds at one seam keep surfacing defects without converging on their source, name what the audit is for, dispatch one blind lens per station of the stream the defect moves along, locate the source, and plan from the source. A subject that reprices on every edit (a count, a census) is not a seam; drop the claim.
|
|
@@ -136,10 +136,9 @@ rest of the layer either fits inside it or takes another approval.
|
|
|
136
136
|
moving target the user cannot approve in time. Publish a layer's opening package with exactly
|
|
137
137
|
one attempt.
|
|
138
138
|
- Retry only an upload that failed **inside** an already-open window. `EOTP` there is intermittent
|
|
139
|
-
contention rather than the window closing: retry
|
|
140
|
-
the layer ends.
|
|
141
|
-
|
|
142
|
-
and causes the moving approval target.
|
|
139
|
+
contention rather than the window closing: retry while the window stays open, and retry a failed
|
|
140
|
+
set after the layer ends. These failures carry similar codes: a retry clears in-window
|
|
141
|
+
contention and moves the approval target.
|
|
143
142
|
- Expect a large layer to outlast one window. Size batches to what uploads in five minutes and
|
|
144
143
|
name each planned approval point to the user, rather than discovering them mid-run.
|
|
145
144
|
- The contract's serialization law binds every upload in the window, and
|
|
@@ -25,4 +25,4 @@ A map is mechanical; reading is not. Run the map first, hand it to the reader, a
|
|
|
25
25
|
## Refuse
|
|
26
26
|
|
|
27
27
|
- A question that needs reading at depth or a judgment: route it to `grok`, `distiller`, or the reviewer the size gate names, with the map attached.
|
|
28
|
-
- A census over a term
|
|
28
|
+
- A census over a term short enough to match inside unrelated words, without `--paths`.
|
|
@@ -50,6 +50,8 @@ Stop and report (expected, found, evidence, done or not done, one hypothesis) on
|
|
|
50
50
|
|
|
51
51
|
**Observations, not criteria.** TIMING_SENSITIVE_OR_TREE_WIDE_GATES the unit reports and the Orchestrator re-runs.
|
|
52
52
|
|
|
53
|
+
**Measurement.** FIXTURE_KINDS: the realistic heavy loads a cost claim is read under, named by kind; the unit sizes and reads them per `.claude/rules/quality.md` § Performance.
|
|
54
|
+
|
|
53
55
|
## Review evidence
|
|
54
56
|
|
|
55
57
|
The actual diff and `git status --porcelain` for a code change; the capture portfolio for a rendered surface; the proposal, the canon it must satisfy, and its motivation for a process proposal.
|
|
@@ -21,7 +21,7 @@ node .agents/skills/orkestrel-dispatch/scripts/launch.ts --journal tmp/cursor/<u
|
|
|
21
21
|
|
|
22
22
|
- Write the brief to `tmp/cursor/<unit>-brief.md` with `scripts/brief.ts --lane cursor`; the prompt is a pointer to it.
|
|
23
23
|
- Read the answer and the session id with `node .agents/skills/orkestrel-dispatch/scripts/result.ts --cursor tmp/cursor/<unit>.jsonl`. The `init` event carries the session id; resume through the CLI's `--resume` option, probed before its first use.
|
|
24
|
-
- A driver runs a lane
|
|
24
|
+
- A driver runs a lane itself when the lane finishes well inside the foreground command cap of the harness running it (on Claude Code, `.claude/AGENTS.md` § Dispatch), and returns the result. For anything longer its job ends at drafting: return the brief path, the resolved command, and the journal path. A driver never recommends a cap and never detaches a run.
|
|
25
25
|
- A driver pinned read-only writes nothing: it returns the brief text, its intended path, the resolved command, and the journal paths, and the Orchestrator writes and launches.
|
|
26
26
|
|
|
27
27
|
## Containment
|
|
@@ -17,7 +17,7 @@ Read `.agents/transports/codex.md` and follow it exactly. It owns the command, t
|
|
|
17
17
|
1. Take the dispatch's brief, or write one to `tmp/codex/<unit>-brief.md` from the dispatch's objective, evidence slice, claims, scope, and return shape. For an audit, the brief names `tmp/units/<unit>-claims.md` and the `orkestrel-falsify` verdict shape.
|
|
18
18
|
2. Run `node .agents/skills/orkestrel-dispatch/scripts/brief.ts --check <brief>` and fix every missing path.
|
|
19
19
|
3. Resolve the `codex exec` command per the transport, as the `launch.ts` line it shows.
|
|
20
|
-
4. Return the brief path, the resolved command, and the journal path.
|
|
20
|
+
4. Return the brief path, the resolved command, and the journal path. When a bounded question finishes well inside the foreground command cap (`.claude/AGENTS.md` § Dispatch), run it yourself and return the answer read with `scripts/result.ts --codex`, with the journal path and session id; launch nothing longer, because the Orchestrator launches it under a cap.
|
|
21
21
|
|
|
22
22
|
## Refuse
|
|
23
23
|
|
|
@@ -17,7 +17,7 @@ Read `.agents/transports/cursor.md` and follow it exactly. It owns the model pin
|
|
|
17
17
|
1. Require a bounded question and an exact file scope from the dispatch. Refuse an unbounded one.
|
|
18
18
|
2. Write the brief to `tmp/cursor/<unit>-brief.md`: read-only, the evidence sought, `file:line` pointers required, no raw dumps, no decisions.
|
|
19
19
|
3. Resolve the command per the transport: `node .agents/skills/orkestrel-dispatch/scripts/bench.ts --cursor --resolve` prints the entry, and the transport shows the `launch.ts` line.
|
|
20
|
-
4.
|
|
20
|
+
4. Run the command yourself only as `.agents/transports/cursor.md` § Command allows, and return the answer read with `scripts/result.ts --cursor`. Otherwise return the brief path, the resolved command, and the journal path; the Orchestrator launches it under a cap.
|
|
21
21
|
5. Launch with `--status`, so `launch.ts` records `git status --porcelain` before and after. Any change is a deviation.
|
|
22
22
|
|
|
23
23
|
## Return
|
|
@@ -46,9 +46,9 @@ so network-controlled descriptions never enter agent instruction context.
|
|
|
46
46
|
| Package | Version | Layer | Runtime dependencies | Peer dependencies |
|
|
47
47
|
| ----------------------- | -------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
|
|
48
48
|
| `@orkestrel/abort` | `0.0.12` | L1 | `@orkestrel/contract` `^0.0.18` | |
|
|
49
|
-
| `@orkestrel/agent` | `0.0.
|
|
49
|
+
| `@orkestrel/agent` | `0.0.26` | L5 | `@orkestrel/tool` `^0.0.18`, `@orkestrel/abort` `^0.0.12`, `@orkestrel/queue` `^0.0.16`, `@orkestrel/budget` `^0.0.12`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/timeout` `^0.0.12`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.17`, `@orkestrel/workflow` `^0.0.21`, `@orkestrel/workspace` `^0.0.11` | |
|
|
50
50
|
| `@orkestrel/brief` | `0.0.10` | L4 | `@orkestrel/reason` `^0.0.12`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.18`, `@orkestrel/interpret` `^0.0.15` | |
|
|
51
|
-
| `@orkestrel/browser` | `0.0.
|
|
51
|
+
| `@orkestrel/browser` | `0.0.24` | L5 | `@orkestrel/mcp` `^0.0.36`, `@orkestrel/html` `^0.0.12`, `@orkestrel/pool` `^0.0.15`, `@orkestrel/tool` `^0.0.18`, `@orkestrel/router` `^0.0.16`, `@orkestrel/server` `^0.0.22`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/markdown` `^0.0.17`, `@orkestrel/websocket` `^0.0.14` | |
|
|
52
52
|
| `@orkestrel/budget` | `0.0.12` | L1 | `@orkestrel/contract` `^0.0.18` | |
|
|
53
53
|
| `@orkestrel/codec` | `0.0.5` | L1 | `@orkestrel/contract` `^0.0.18` | |
|
|
54
54
|
| `@orkestrel/console` | `0.0.15` | L2 | `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.18` | |
|
|
@@ -68,8 +68,8 @@ so network-controlled descriptions never enter agent instruction context.
|
|
|
68
68
|
| `@orkestrel/msg` | `0.0.12` | L1 | `@orkestrel/contract` `^0.0.18` | |
|
|
69
69
|
| `@orkestrel/ndjson` | `0.0.11` | L1 | `@orkestrel/contract` `^0.0.18` | |
|
|
70
70
|
| `@orkestrel/ollama` | `0.0.20` | L6 | `@orkestrel/tool` `^0.0.18`, `@orkestrel/agent` `^0.0.25`, `@orkestrel/budget` `^0.0.12`, `@orkestrel/ndjson` `^0.0.11`, `@orkestrel/contract` `^0.0.19` | |
|
|
71
|
-
| `@orkestrel/pool` | `0.0.
|
|
72
|
-
| `@orkestrel/probe` | `0.0.
|
|
71
|
+
| `@orkestrel/pool` | `0.0.15` | L2 | `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.19` | |
|
|
72
|
+
| `@orkestrel/probe` | `0.0.20` | L5 | `@orkestrel/lsp` `^0.0.10`, `@orkestrel/mcp` `^0.0.36`, `@orkestrel/tool` `^0.0.18`, `@orkestrel/queue` `^0.0.16`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/timeout` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | `vitest` `^4.1.11`, `typescript` `^6.0.3` |
|
|
73
73
|
| `@orkestrel/process` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.18` | |
|
|
74
74
|
| `@orkestrel/program` | `0.0.15` | L4 | `@orkestrel/rater` `^0.0.16`, `@orkestrel/reason` `^0.0.12`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.18`, `@orkestrel/qualifier` `^0.0.16` | |
|
|
75
75
|
| `@orkestrel/qualifier` | `0.0.16` | L3 | `@orkestrel/reason` `^0.0.12`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.18` | |
|
|
@@ -78,7 +78,7 @@ so network-controlled descriptions never enter agent instruction context.
|
|
|
78
78
|
| `@orkestrel/reason` | `0.0.12` | L2 | `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.18` | |
|
|
79
79
|
| `@orkestrel/relation` | `0.0.15` | L3 | `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.17` | |
|
|
80
80
|
| `@orkestrel/router` | `0.0.16` | L2 | `@orkestrel/abort` `^0.0.12`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.18` | |
|
|
81
|
-
| `@orkestrel/scaffold` | `0.0.
|
|
81
|
+
| `@orkestrel/scaffold` | `0.0.91` | L3 | `@orkestrel/console` `^0.0.15`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/process` `^0.0.14`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/markdown` `^0.0.17`, `@orkestrel/template` `^0.0.9` | |
|
|
82
82
|
| `@orkestrel/sea` | `0.0.18` | L3 | `@orkestrel/emitter` `^0.0.11`, `@orkestrel/process` `^0.0.14`, `@orkestrel/contract` `^0.0.18` | |
|
|
83
83
|
| `@orkestrel/server` | `0.0.22` | L3 | `@orkestrel/abort` `^0.0.12`, `@orkestrel/codec` `^0.0.5`, `@orkestrel/router` `^0.0.16`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/timeout` `^0.0.12`, `@orkestrel/contract` `^0.0.19` | |
|
|
84
84
|
| `@orkestrel/sqlite` | `0.0.14` | L1 | `@orkestrel/contract` `^0.0.19` | |
|
|
@@ -90,10 +90,10 @@ so network-controlled descriptions never enter agent instruction context.
|
|
|
90
90
|
| `@orkestrel/test` | `0.0.24` | L1 | `@orkestrel/contract` `^0.0.18` | `vitest` `^4.1.11` |
|
|
91
91
|
| `@orkestrel/timeout` | `0.0.12` | L1 | `@orkestrel/contract` `^0.0.18` | |
|
|
92
92
|
| `@orkestrel/tool` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.19` | |
|
|
93
|
-
| `@orkestrel/toolbox` | `0.0.
|
|
93
|
+
| `@orkestrel/toolbox` | `0.0.17` | L6 | `@orkestrel/form` `^0.0.8`, `@orkestrel/tool` `^0.0.18`, `@orkestrel/agent` `^0.0.26`, `@orkestrel/server` `^0.0.22`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.17`, `@orkestrel/relation` `^0.0.15`, `@orkestrel/terminal` `^0.0.18`, `@orkestrel/workflow` `^0.0.21`, `@orkestrel/workspace` `^0.0.11` | |
|
|
94
94
|
| `@orkestrel/websocket` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.18` | |
|
|
95
|
-
| `@orkestrel/worker` | `0.0.
|
|
96
|
-
| `@orkestrel/workflow` | `0.0.
|
|
95
|
+
| `@orkestrel/worker` | `0.0.15` | L4 | `@orkestrel/pool` `^0.0.14`, `@orkestrel/queue` `^0.0.16`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.17` | |
|
|
96
|
+
| `@orkestrel/workflow` | `0.0.21` | L4 | `@orkestrel/abort` `^0.0.12`, `@orkestrel/queue` `^0.0.16`, `@orkestrel/budget` `^0.0.12`, `@orkestrel/emitter` `^0.0.11`, `@orkestrel/timeout` `^0.0.12`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.17` | |
|
|
97
97
|
| `@orkestrel/workspace` | `0.0.11` | L3 | `@orkestrel/emitter` `^0.0.11`, `@orkestrel/contract` `^0.0.19`, `@orkestrel/database` `^0.0.17` | |
|
|
98
98
|
|
|
99
99
|
<!-- /orkestrel:catalog -->
|
|
@@ -13,7 +13,7 @@ You design. You hold no edit tool and run no command; your final message is the
|
|
|
13
13
|
|
|
14
14
|
1. Read the brief, `AGENTS.md`, the rules whose `paths` match the subject, the named skill, the guide, and the supplied distillate. Work from the brief alone; never look for or reconcile the other lane's answer.
|
|
15
15
|
2. Hold the lane the dispatch names and say which one: subjective (shape, naming, ergonomics, design fit) or objective (correctness, constraints, what the contracts permit).
|
|
16
|
-
3. Propose one design. Name
|
|
16
|
+
3. Propose one design. Name each real alternative that a constraint favors and why the design wins; leave out an option nothing favors.
|
|
17
17
|
4. Cut every unit to a fully specified brief a cheap executor could implement; name each unit's role and engine, owned files, dependencies, and acceptance criteria.
|
|
18
18
|
5. Name every judgment call under `Tensions` for the other lane or the Orchestrator to rule.
|
|
19
19
|
|
|
@@ -14,7 +14,7 @@ You gather cited facts from primary sources. You decide nothing.
|
|
|
14
14
|
|
|
15
15
|
1. Take one bounded question and the sources it names: official documentation, release notes, the installed declaration under `node_modules`.
|
|
16
16
|
2. Fetch and read each source. Never answer from memory.
|
|
17
|
-
3. Record each fact with its URL or `file:line` and
|
|
17
|
+
3. Record each fact with its URL or `file:line` and the shortest supporting quote that carries the fact, never a passage.
|
|
18
18
|
4. Put anything a primary source did not settle under `Unknowns` rather than guessing.
|
|
19
19
|
|
|
20
20
|
## Return
|
|
@@ -18,4 +18,4 @@ You locate. You do not read at depth, edit, or judge.
|
|
|
18
18
|
|
|
19
19
|
## Return
|
|
20
20
|
|
|
21
|
-
`Question`, `Hits` (cited), `Shape` (
|
|
21
|
+
`Question`, `Hits` (cited), `Shape` (the shortest summary that places every part of the question), `Not found` (patterns that returned nothing). Nothing else.
|
|
@@ -29,7 +29,7 @@ Hard targets:
|
|
|
29
29
|
- Ungrouped option keys: one word.
|
|
30
30
|
- Grouped option key: the configured entity noun; every leaf remains one word.
|
|
31
31
|
- Events: one present-tense verb or noun.
|
|
32
|
-
- Private methods:
|
|
32
|
+
- Private methods: as many words as name the step unambiguously, and no more.
|
|
33
33
|
|
|
34
34
|
The rule does not apply to standalone helpers, type names with role suffixes, or qualified constants.
|
|
35
35
|
|
|
@@ -105,7 +105,7 @@ Choose one event model per environment. `Emitter<TMap>` remains the default outs
|
|
|
105
105
|
- Never publish a generic `status` event carrying a transition value; publish each transition as its own event.
|
|
106
106
|
- Type errors as `unknown`.
|
|
107
107
|
- Use empty tuples for signals and labeled tuple elements for IDE clarity.
|
|
108
|
-
- Keep an entity's event map focused
|
|
108
|
+
- Keep an entity's event map focused on the transitions and operations a consumer observes.
|
|
109
109
|
|
|
110
110
|
## Validation and contracts
|
|
111
111
|
|
|
@@ -44,6 +44,17 @@ paths:
|
|
|
44
44
|
- Baseline a published-artifact claim against the published artifact (the tarball, the deployed asset). Prove a module cycle by loading the built entry points.
|
|
45
45
|
- Promote an instrument that settled a claim into a test, with its control, before accepting the work it settled.
|
|
46
46
|
|
|
47
|
+
## Performance
|
|
48
|
+
|
|
49
|
+
- Keep runtime cost reasonable and measurable. When a change claims a cost or a gain in speed, name the instrument that reads it and report each reading with its run.
|
|
50
|
+
- Change code for speed only when a measurement shows a gain worth having under the heavy load that real pages or callers produce. Never justify a change with an invented load.
|
|
51
|
+
- Refuse a micro optimization (hoisting a small array, caching one cheap read, shaving a constant) unless its own measurement shows a gain worth having.
|
|
52
|
+
- Keep an algorithmic repair (a superlinear term, a repeated layout) when the measurement shows it.
|
|
53
|
+
- Before the run, size the fixtures, the sample count, and the threshold to the case, and state the reasoning and the result that makes the change worth keeping.
|
|
54
|
+
- Read the difference between methods against each side's reported uncertainty, and record no difference smaller than the result stated before the run.
|
|
55
|
+
- Report every measurement with the host's other load during the run.
|
|
56
|
+
- Rule a cost finding advisory unless it shows its effect under a realistic load, and never carry an advisory into a fix brief as a required change; `.agents/skills/orkestrel-falsify/SKILL.md` § Verdict shape places it in a review lane's return.
|
|
57
|
+
|
|
47
58
|
## Ecosystem reuse
|
|
48
59
|
|
|
49
60
|
- Prove a semantic difference before keeping a local variant of an installed primitive.
|
|
@@ -25,7 +25,7 @@ paths:
|
|
|
25
25
|
population. The policy sweep (`tests/setupPolicy.ts`) enforces both directions.
|
|
26
26
|
- Prefer test filenames matching entrypoints: `index.test.ts` for `index.ts`, `main.test.ts` for `main.ts`.
|
|
27
27
|
- Tests are deterministic: identical inputs produce identical results.
|
|
28
|
-
- Keep default suites fast:
|
|
28
|
+
- Keep default suites fast: give each timer the shortest real duration that still separates the orderings the test asserts on a loaded host, and make no network calls.
|
|
29
29
|
- Use real implementations and small scenarios. Never use mocks, behavioral fakes, module replacement, or framework spies for project-owned or integrated behavior.
|
|
30
30
|
- Use recorders for calls/events, temporary resources for stateful boundaries, protocol-faithful fixture servers for deterministic network peers, and the real external service when its behavior is the claim.
|
|
31
31
|
- Prefer inert customizable data and input stubs.
|
|
@@ -127,13 +127,12 @@ Run a probe before relying on an unverified belief about behaviour: what a funct
|
|
|
127
127
|
configuration resolves to, whether a path is reached at all. Prefer a probe to an argument whenever
|
|
128
128
|
the probe is cheap.
|
|
129
129
|
|
|
130
|
-
When the question is whether the difference between methods is
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
commit baseline output.
|
|
130
|
+
When the question is whether the difference between methods is worth having, write a guarded bench
|
|
131
|
+
block beside the probe test, run the `test:bench` script, and size its fixtures, declare its
|
|
132
|
+
threshold, and read its result per `.claude/rules/quality.md` § Performance. A settled difference
|
|
133
|
+
that underwrites an implementation choice promotes with its test into the mirrored suite and keeps
|
|
134
|
+
its guarded block there while that choice stands. A deterministic relationship promotes as an
|
|
135
|
+
ordinary assertion, so delete the block. Never commit baseline output.
|
|
137
136
|
|
|
138
137
|
These rules bind every probe:
|
|
139
138
|
|
|
@@ -56,7 +56,8 @@
|
|
|
56
56
|
- Cut every clause that persuades, reassures, or explains to a person.
|
|
57
57
|
- Give a rule one home. Point at it from elsewhere; never restate it.
|
|
58
58
|
- Keep an example only when it disambiguates the rule.
|
|
59
|
-
-
|
|
59
|
+
- When an instruction file or a brief governs a quantity, state the property the quantity must serve and leave the figure to the case: never fix a fixture size, a sample count, a percentage, or a threshold, and describe a fixture by its kind and the load it represents. Keep a figure only where it is a contract: a limit a protocol, format, standard, or external tool fixes, an exit code, a measurement with its run, a version, a date, or a cardinality a design law fixes (one word per name, one writer per checkout).
|
|
60
|
+
- Keep `AGENTS.md` to the laws every task needs and the always-loaded set small: move a procedure into a skill and scope a rule with `paths`.
|
|
60
61
|
|
|
61
62
|
## Substitutions
|
|
62
63
|
|
|
@@ -8,8 +8,8 @@ Gather cited facts from primary sources. Decide nothing.
|
|
|
8
8
|
|
|
9
9
|
Take one bounded question and the sources it names: official documentation, release notes, the
|
|
10
10
|
installed declaration under node_modules. Read each source; never answer from memory. Record each
|
|
11
|
-
fact with its URL or file:line and
|
|
12
|
-
source did not settle under Unknowns.
|
|
11
|
+
fact with its URL or file:line and the shortest supporting quote that carries the fact, never a
|
|
12
|
+
passage. Put anything a primary source did not settle under Unknowns.
|
|
13
13
|
|
|
14
14
|
Return only: Question, Facts (claim, source, date, quote), Matrix when asked (each row ending
|
|
15
15
|
implement, repair, retain, or exclude with evidence), Unknowns. Never spawn another agent.
|
|
@@ -13,6 +13,6 @@ a match. Refuse a dispatch that names no map and asks for one. Return every hit
|
|
|
13
13
|
one-line shape note, grouped by the question's parts, and name the search patterns and roots you
|
|
14
14
|
used.
|
|
15
15
|
|
|
16
|
-
Return only: Question, Hits, Shape (
|
|
16
|
+
Return only: Question, Hits, Shape (the shortest summary that places every part of the question), Not found (patterns that returned nothing).
|
|
17
17
|
Never spawn another agent.
|
|
18
18
|
"""
|