@venizia/vulcan 0.4.10-2 → 0.4.10-21

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 (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -1,332 +0,0 @@
1
- import { createHash } from 'node:crypto';
2
- import {
3
- appendFileSync,
4
- lstatSync,
5
- mkdirSync,
6
- readdirSync,
7
- readFileSync,
8
- rmSync,
9
- writeFileSync,
10
- } from 'node:fs';
11
- import { join } from 'node:path';
12
- import { LocalScan } from '../local/scan.ts';
13
- import { ClaimClasses } from '../signals/constants.ts';
14
- import { ShapeClasses } from './shape.ts';
15
-
16
- const isKnownClass = (value: string): boolean =>
17
- ShapeClasses.isValid(value) || ClaimClasses.isValid(value);
18
-
19
- export class ViolationConstants {
20
- /** One line per checked reply that broke the shape: the date and the classes, never the reply. */
21
- static readonly LOG_FILE = 'violations.jsonl';
22
- /** One note per session under the cache: its last checked reply's classes, for that session's next reminder. */
23
- static readonly NOTES_DIRECTORY = 'cache/replies';
24
- /** The note name of an event that carries no session id. */
25
- static readonly DEFAULT_SESSION = 'default';
26
- static readonly SESSION_NAME_MAX = 64;
27
- /** The most notes kept; a write removes the oldest beyond it. */
28
- static readonly NOTES_MAX = 32;
29
- /** A cached last reply older than this is ignored: the reminder is about the reply just before. */
30
- static readonly LAST_MAX_AGE_MS = 30 * 60 * 1000;
31
- /** A reply was sent back this recently: it is not sent back again, whatever the client says about a retry. */
32
- static readonly BLOCK_COOLDOWN_MS = 2 * 60 * 1000;
33
- static readonly LOG_MAX_BYTES = 512 * 1024;
34
- }
35
-
36
- /** `.agents/local/<file>` of a trusted project, or `undefined`; a symlinked file is never followed. */
37
- const fileOf = (opts: { root: string; name: string }): string | undefined => {
38
- const local = LocalScan.localRootOf({ root: opts.root });
39
-
40
- if (local === undefined) {
41
- return undefined;
42
- }
43
-
44
- const path = join(local, opts.name);
45
-
46
- try {
47
- return lstatSync(path).isFile() ? path : undefined;
48
- } catch (error) {
49
- // Not there yet is fine; anything else (no permission, not a file) means the path is not ours to write.
50
- return error instanceof Error && 'code' in error && error.code === 'ENOENT' ? path : undefined;
51
- }
52
- };
53
-
54
- /**
55
- * A session id as a file name: its safe characters, then a short hash of the whole id, so two ids
56
- * that reduce to the same characters (or share a long prefix) never share a note. No id is `default`.
57
- */
58
- const noteName = (opts: { session?: string }): string => {
59
- const session = opts.session ?? '';
60
-
61
- if (session === '') {
62
- return ViolationConstants.DEFAULT_SESSION;
63
- }
64
-
65
- const safe = session
66
- .replace(/[^A-Za-z0-9_-]/g, '_')
67
- .slice(0, ViolationConstants.SESSION_NAME_MAX);
68
-
69
- return `${safe}-${createHash('sha256').update(session).digest('hex').slice(0, 8)}`;
70
- };
71
-
72
- /**
73
- * The note folder of a trusted `.agents/local/`; neither `cache/` nor the folder may be a link or not
74
- * a directory. Created only when `opts.create` is set.
75
- */
76
- const notesDirectoryOf = (opts: { root: string; create: boolean }): string | undefined => {
77
- const local = LocalScan.localRootOf({ root: opts.root });
78
-
79
- if (local === undefined) {
80
- return undefined;
81
- }
82
-
83
- try {
84
- let current = local;
85
-
86
- for (const part of ViolationConstants.NOTES_DIRECTORY.split('/')) {
87
- current = join(current, part);
88
-
89
- const kind = lstatSync(current, { throwIfNoEntry: false });
90
-
91
- if (kind === undefined) {
92
- if (!opts.create) {
93
- return undefined;
94
- }
95
-
96
- mkdirSync(current, { recursive: true });
97
- } else if (!kind.isDirectory()) {
98
- return undefined;
99
- }
100
- }
101
-
102
- return current;
103
- } catch {
104
- return undefined;
105
- }
106
- };
107
-
108
- /** The note file of one session; a symlinked file is never followed. */
109
- const noteFileOf = (opts: {
110
- root: string;
111
- session?: string;
112
- create: boolean;
113
- }): string | undefined => {
114
- const directory = notesDirectoryOf({ root: opts.root, create: opts.create });
115
-
116
- if (directory === undefined) {
117
- return undefined;
118
- }
119
-
120
- const path = join(directory, `${noteName({ session: opts.session })}.json`);
121
-
122
- try {
123
- const kind = lstatSync(path, { throwIfNoEntry: false });
124
-
125
- return kind === undefined || kind.isFile() ? path : undefined;
126
- } catch {
127
- return undefined;
128
- }
129
- };
130
-
131
- const readNote = (opts: { root: string; session?: string }): Record<string, unknown> => {
132
- const path = noteFileOf({ root: opts.root, session: opts.session, create: false });
133
-
134
- if (path === undefined) {
135
- return {};
136
- }
137
-
138
- try {
139
- const note: unknown = JSON.parse(readFileSync(path, 'utf8'));
140
-
141
- return typeof note === 'object' && note !== null
142
- ? Object.fromEntries(Object.entries(note))
143
- : {};
144
- } catch {
145
- return {};
146
- }
147
- };
148
-
149
- /** Removes the notes older than the reminder window and the oldest beyond the cap, so the folder never grows. A note that cannot be removed is left. */
150
- const pruneNotes = (opts: { root: string; now: number }): void => {
151
- const directory = notesDirectoryOf({ root: opts.root, create: false });
152
-
153
- if (directory === undefined) {
154
- return;
155
- }
156
-
157
- const notes = readdirSync(directory)
158
- .filter((name) => name.endsWith('.json'))
159
- .flatMap((name) => {
160
- const path = join(directory, name);
161
- const kind = lstatSync(path, { throwIfNoEntry: false });
162
-
163
- return kind?.isFile() === true ? [{ path, modifiedAt: kind.mtimeMs }] : [];
164
- })
165
- .sort((first, second) => second.modifiedAt - first.modifiedAt);
166
-
167
- notes.forEach((note, index) => {
168
- if (
169
- index >= ViolationConstants.NOTES_MAX ||
170
- opts.now - note.modifiedAt > ViolationConstants.LAST_MAX_AGE_MS
171
- ) {
172
- rmSync(note.path, { force: true });
173
- }
174
- });
175
- };
176
-
177
- const isOversized = (opts: { path: string }): boolean => {
178
- try {
179
- return lstatSync(opts.path).size > ViolationConstants.LOG_MAX_BYTES;
180
- } catch {
181
- return false;
182
- }
183
- };
184
-
185
- export class ViolationLog {
186
- /** Records one checked reply: the log when it broke the shape, and always the session's last-reply note. */
187
- static recordReply(opts: {
188
- root: string;
189
- classes: string[];
190
- session?: string;
191
- now?: Date;
192
- }): void {
193
- const now = opts.now ?? new Date();
194
- const log = fileOf({ root: opts.root, name: ViolationConstants.LOG_FILE });
195
-
196
- if (log !== undefined && opts.classes.length > 0 && !isOversized({ path: log })) {
197
- appendFileSync(
198
- log,
199
- `${JSON.stringify({ date: now.toISOString().slice(0, 10), classes: opts.classes })}\n`,
200
- { mode: 0o600 },
201
- );
202
- }
203
-
204
- const last = noteFileOf({ root: opts.root, session: opts.session, create: true });
205
-
206
- if (last !== undefined) {
207
- const { blockedAt } = readNote({ root: opts.root, session: opts.session });
208
-
209
- writeFileSync(
210
- last,
211
- `${JSON.stringify({ at: now.getTime(), classes: opts.classes, ...(typeof blockedAt === 'number' ? { blockedAt } : {}) })}\n`,
212
- { mode: 0o600 },
213
- );
214
- pruneNotes({ root: opts.root, now: Date.now() });
215
- }
216
- }
217
-
218
- /** Notes that a reply of this session was just sent back, so a second one is never sent back right after it. */
219
- static markBlocked(opts: { root: string; session?: string; now?: Date }): void {
220
- const last = noteFileOf({ root: opts.root, session: opts.session, create: true });
221
-
222
- if (last !== undefined) {
223
- writeFileSync(
224
- last,
225
- `${JSON.stringify({ ...readNote({ root: opts.root, session: opts.session }), blockedAt: (opts.now ?? new Date()).getTime() })}\n`,
226
- { mode: 0o600 },
227
- );
228
- }
229
- }
230
-
231
- static wasBlockedRecently(opts: { root: string; session?: string; now?: number }): boolean {
232
- const { blockedAt } = readNote({ root: opts.root, session: opts.session });
233
-
234
- return (
235
- typeof blockedAt === 'number' &&
236
- (opts.now ?? Date.now()) - blockedAt <= ViolationConstants.BLOCK_COOLDOWN_MS
237
- );
238
- }
239
-
240
- /** The size of the violation log in bytes, 0 when there is none or it is not ours to read. */
241
- static violationBytes(opts: { root: string }): number {
242
- const log = fileOf({ root: opts.root, name: ViolationConstants.LOG_FILE });
243
-
244
- return log === undefined ? 0 : (lstatSync(log, { throwIfNoEntry: false })?.size ?? 0);
245
- }
246
-
247
- /** The classes the previous reply of this session broke, or none when there is no note or it is stale. */
248
- static readLastClasses(opts: { root: string; session?: string; now?: number }): string[] {
249
- const last = noteFileOf({ root: opts.root, session: opts.session, create: false });
250
-
251
- if (last === undefined) {
252
- return [];
253
- }
254
-
255
- try {
256
- const note: unknown = JSON.parse(readFileSync(last, 'utf8'));
257
-
258
- if (typeof note !== 'object' || note === null || !('at' in note) || !('classes' in note)) {
259
- return [];
260
- }
261
-
262
- const { at, classes } = note;
263
-
264
- if (
265
- typeof at !== 'number' ||
266
- (opts.now ?? Date.now()) - at > ViolationConstants.LAST_MAX_AGE_MS ||
267
- !Array.isArray(classes)
268
- ) {
269
- return [];
270
- }
271
-
272
- return classes.filter(
273
- (value): value is string => typeof value === 'string' && isKnownClass(value),
274
- );
275
- } catch {
276
- return [];
277
- }
278
- }
279
-
280
- /** Violations by class across the log, and the number of days it covers; empty when there is no log. */
281
- static readCounts(opts: { root: string }): {
282
- byClass: Map<string, number>;
283
- replies: number;
284
- days: number;
285
- } {
286
- const byClass = new Map<string, number>();
287
- const days = new Set<string>();
288
- let replies = 0;
289
- const log = fileOf({ root: opts.root, name: ViolationConstants.LOG_FILE });
290
-
291
- if (log === undefined) {
292
- return { byClass, replies, days: 0 };
293
- }
294
-
295
- let text = '';
296
-
297
- try {
298
- text = readFileSync(log, 'utf8');
299
- } catch {
300
- return { byClass, replies, days: 0 };
301
- }
302
-
303
- for (const line of text.split('\n')) {
304
- try {
305
- const entry: unknown = JSON.parse(line);
306
-
307
- if (
308
- typeof entry === 'object' &&
309
- entry !== null &&
310
- 'classes' in entry &&
311
- Array.isArray(entry.classes)
312
- ) {
313
- replies += 1;
314
-
315
- if ('date' in entry && typeof entry.date === 'string') {
316
- days.add(entry.date);
317
- }
318
-
319
- for (const value of entry.classes) {
320
- if (typeof value === 'string' && isKnownClass(value)) {
321
- byClass.set(value, (byClass.get(value) ?? 0) + 1);
322
- }
323
- }
324
- }
325
- } catch {
326
- // A damaged line is skipped: the log is advisory.
327
- }
328
- }
329
-
330
- return { byClass, replies, days: days.size };
331
- }
332
- }
@@ -1,73 +0,0 @@
1
- import { ClaimClasses, ClaimWords } from './constants.ts';
2
- import type { ISignalState } from './state.ts';
3
-
4
- const LETTER_OR_DIGIT = String.raw`\p{L}\p{N}`;
5
-
6
- const escaped = (opts: { text: string }): string =>
7
- opts.text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
8
-
9
- /** The sentences a reply asserts: code, quotes and questions are not assertions, and each sentence stands alone. */
10
- const sentencesOf = (opts: { text: string }): string[] =>
11
- opts.text
12
- .normalize('NFC')
13
- .replace(/```[\s\S]*?```/g, ' ')
14
- .replace(/`[^`]*`/g, ' ')
15
- .split('\n')
16
- .filter((line) => !line.trimStart().startsWith('>'))
17
- .join('\n')
18
- .split(/(?<=[.!?…。!?])\s+|\n+/)
19
- .map((sentence) => sentence.trim())
20
- .filter((sentence) => sentence !== '' && !sentence.endsWith('?'));
21
-
22
- const hasWord = (opts: { sentence: string; word: string }): boolean =>
23
- new RegExp(
24
- `(?<![${LETTER_OR_DIGIT}])${escaped({ text: opts.word.normalize('NFC') })}(?![${LETTER_OR_DIGIT}])`,
25
- 'iu',
26
- ).test(opts.sentence);
27
-
28
- const isDenied = (opts: { sentence: string }): boolean =>
29
- ClaimWords.NEGATIONS.some((word) =>
30
- word === "n't"
31
- ? opts.sentence.toLowerCase().includes(word)
32
- : hasWord({ sentence: opts.sentence, word }),
33
- );
34
-
35
- /** Whether a sentence of the reply asserts one of the phrases, and does not deny it. */
36
- const asserts = (opts: { text: string; words: string[] }): boolean =>
37
- sentencesOf({ text: opts.text }).some(
38
- (sentence) => !isDenied({ sentence }) && opts.words.some((word) => hasWord({ sentence, word })),
39
- );
40
-
41
- export class ReplyClaims {
42
- /**
43
- * What the reply claims against what the turn's calls show. A claim that something is published, released
44
- * or live needs a public-state probe in the turn; a claim that the checks pass is contradicted while a gate
45
- * of the turn still failed on its latest run. Phrases match whole words in a sentence that does not deny,
46
- * ask or quote; English plus any the project adds. Logged, never blocked: a match is a hint, not proof.
47
- */
48
- static check(opts: {
49
- text: string;
50
- state: ISignalState;
51
- publicWords?: string[];
52
- doneWords?: string[];
53
- }): string[] {
54
- const classes: string[] = [];
55
- const { state } = opts;
56
-
57
- if (
58
- asserts({ text: opts.text, words: [...ClaimWords.PUBLIC, ...(opts.publicWords ?? [])] }) &&
59
- state.probeAt < state.turnAt
60
- ) {
61
- classes.push(ClaimClasses.PUBLIC_CLAIM_NO_PROBE);
62
- }
63
-
64
- if (
65
- asserts({ text: opts.text, words: [...ClaimWords.DONE, ...(opts.doneWords ?? [])] }) &&
66
- state.failedGates.length > 0
67
- ) {
68
- classes.push(ClaimClasses.CONTRADICTED_COMPLETION);
69
- }
70
-
71
- return classes;
72
- }
73
- }
@@ -1,137 +0,0 @@
1
- import { createHash } from 'node:crypto';
2
- import { ShellParser } from '../hooks/shell.ts';
3
- import { SignalConstants, WatchedKinds } from './constants.ts';
4
-
5
- const LOCAL_URL = /^https?:\/\/(?:localhost|127\.|0\.0\.0\.0|\[::1\])/;
6
- const GATE_SCRIPTS = new Set(['test', 'lint', 'build', 'typecheck', 'check']);
7
- const GATE_TOOLS = new Set(['tsc', 'vitest', 'jest', 'pytest', 'eslint', 'oxlint']);
8
- const GATE_MAKE_TARGET = /^(?:test|lint|build|check|typecheck|docs|smoke)(?:[-:\w]*)$/;
9
- const READ_VIEWS = new Set(['view', 'list', 'status', 'checks', 'watch']);
10
- const SKILL_FILE =
11
- /(?:^|\/)(?:\.agents\/skills|\.claude\/skills|packages\/[^/]+\/base\/skills)\/([^/]+)\/(?:SKILL\.md|references\/.+|evals\/.+)$/;
12
- const RULES_FILE = /(?:^|\/)(?:\.agents\/rules\.md|packages\/[^/]+\/base\/rules\.md)$/;
13
- const SCRATCH = /(?:^|\/)\.agents\/local\//;
14
-
15
- /** The simple commands of a line as program and arguments; a line that cannot be parsed has none. */
16
- const programsOf = (opts: { command: string }): { name: string; args: string[] }[] => {
17
- try {
18
- return ShellParser.parse({ command: opts.command }).map((simple) => {
19
- const { name, args } = ShellParser.programOf({ command: simple });
20
-
21
- return { name, args };
22
- });
23
- } catch {
24
- return [];
25
- }
26
- };
27
-
28
- const isProbeProgram = (opts: { name: string; args: string[] }): boolean => {
29
- const { name, args } = opts;
30
-
31
- if (name === 'npm') {
32
- return ['view', 'info', 'show', 'dist-tag'].includes(args[0] ?? '');
33
- }
34
-
35
- if (name === 'git') {
36
- return args[0] === 'ls-remote';
37
- }
38
-
39
- if (name === 'gh') {
40
- if (args[0] === 'api') {
41
- return !args.some((arg) => /^(?:-X|--method|-f|-F|--field|--raw-field|--input)$/.test(arg));
42
- }
43
-
44
- return args.some((arg) => READ_VIEWS.has(arg)) && !args.includes('create');
45
- }
46
-
47
- if (name === 'curl') {
48
- const url = args.find((arg) => /^https?:\/\//.test(arg));
49
-
50
- return (
51
- url !== undefined &&
52
- !LOCAL_URL.test(url) &&
53
- !args.some((arg) => /^(?:-X|--request|-d|--data.*|-F|--form|-T)$/.test(arg))
54
- );
55
- }
56
-
57
- return false;
58
- };
59
-
60
- const isGateProgram = (opts: { name: string; args: string[] }): boolean => {
61
- const { name, args } = opts;
62
- const first = args.find((arg) => !arg.startsWith('-')) ?? '';
63
-
64
- if (name === 'bun') {
65
- // `check` is Bun's own type-check (Bun >= 1.4.4), two words like `test`; `tsc` stays in GATE_TOOLS for other projects.
66
- return (
67
- first === 'test' ||
68
- first === 'check' ||
69
- (first === 'run' && GATE_SCRIPTS.has(args[args.indexOf('run') + 1] ?? '')) ||
70
- (first === 'x' && args.includes('vulcan') && args.includes('doctor'))
71
- );
72
- }
73
-
74
- if (name === 'bunx' || name === 'npx') {
75
- return GATE_TOOLS.has(first);
76
- }
77
-
78
- if (name === 'make') {
79
- return args.some((arg) => !arg.startsWith('-') && GATE_MAKE_TARGET.test(arg));
80
- }
81
-
82
- if (name === 'npm' || name === 'pnpm' || name === 'yarn') {
83
- return (
84
- GATE_SCRIPTS.has(first) ||
85
- (first === 'run' && GATE_SCRIPTS.has(args[args.indexOf('run') + 1] ?? ''))
86
- );
87
- }
88
-
89
- if (name === 'cargo' || name === 'go') {
90
- return first === 'test';
91
- }
92
-
93
- if (name === 'vulcan') {
94
- return first === 'doctor';
95
- }
96
-
97
- return GATE_TOOLS.has(name);
98
- };
99
-
100
- export class SignalClassifier {
101
- /** The tool input as a short stable key: the same call twice has the same key. */
102
- static callKeyOf(opts: { tool: string; input: unknown }): string {
103
- return `${opts.tool}:${createHash('sha1')
104
- .update(JSON.stringify(opts.input ?? null))
105
- .digest('hex')
106
- .slice(0, SignalConstants.EVENT_KEY_LENGTH)}`;
107
- }
108
-
109
- /** A command that asks public state: the registry, the forge, a remote, an outside URL; not a write. */
110
- static isPublicProbe(opts: { command: string }): boolean {
111
- return programsOf({ command: opts.command }).some((program) => isProbeProgram(program));
112
- }
113
-
114
- /** The gates a command line runs (tests, lint, build, the project's own gates), each as a short name. */
115
- static gatesOf(opts: { command: string }): string[] {
116
- return programsOf({ command: opts.command })
117
- .filter((program) => isGateProgram(program))
118
- .map((program) =>
119
- [program.name, ...program.args].join(' ').slice(0, SignalConstants.GATE_KEY_LENGTH),
120
- );
121
- }
122
-
123
- /** What an edited file is for the nudge: a skill (with its name), a rules file, or neither. */
124
- static watchedFileOf(opts: { path: string }): { kind: string; name: string } | undefined {
125
- if (SCRATCH.test(opts.path)) {
126
- return undefined;
127
- }
128
-
129
- const skill = SKILL_FILE.exec(opts.path)?.[1];
130
-
131
- if (skill !== undefined) {
132
- return { kind: WatchedKinds.SKILL, name: skill };
133
- }
134
-
135
- return RULES_FILE.test(opts.path) ? { kind: WatchedKinds.RULES, name: opts.path } : undefined;
136
- }
137
- }
@@ -1,88 +0,0 @@
1
- export class SignalConstants {
2
- /** The turn's notes: one JSON line per call, appended, so parallel hook processes never overwrite each other. */
3
- static readonly LOG_FILE = 'cache/signals.jsonl';
4
- /** The log is rewritten smaller at a new turn once it grows past this. */
5
- static readonly COMPACT_BYTES = 32 * 1024;
6
- /** Only the end of an oversized log is read. */
7
- static readonly READ_TAIL_BYTES = 256 * 1024;
8
- static readonly MAX_EVENTS = 30;
9
- /** The same advisory is not repeated inside this window. */
10
- static readonly DEBOUNCE_MS = 5 * 60 * 1000;
11
- static readonly SAME_CALL_LIMIT = 3;
12
- /** Identical calls further apart than this are polling, not a loop. */
13
- static readonly POLL_WINDOW_MS = 60 * 1000;
14
- static readonly ALTERNATION_LENGTH = 6;
15
- static readonly FAILURE_LIMIT = 3;
16
- static readonly FAILURE_WINDOW = 6;
17
- static readonly EVENT_KEY_LENGTH = 12;
18
- static readonly GATE_KEY_LENGTH = 80;
19
- }
20
-
21
- export class EntryKinds {
22
- static readonly TURN = 'turn';
23
- static readonly CALL = 'call';
24
- static readonly NOTE = 'note';
25
- }
26
-
27
- export class WatchedKinds {
28
- static readonly SKILL = 'skill';
29
- static readonly RULES = 'rules';
30
- }
31
-
32
- /** What a reply claimed that the turn's tool calls do not back. Both are logged, never blocking. */
33
- export class ClaimClasses {
34
- static readonly CONTRADICTED_COMPLETION = 'contradicted-completion';
35
- static readonly PUBLIC_CLAIM_NO_PROBE = 'public-claim-no-probe';
36
- static readonly SCHEME_SET = new Set<string>([
37
- this.CONTRADICTED_COMPLETION,
38
- this.PUBLIC_CLAIM_NO_PROBE,
39
- ]);
40
- static isValid(value: string): boolean {
41
- return this.SCHEME_SET.has(value);
42
- }
43
- }
44
-
45
- /** Phrases that say something is in public state, and that the work is complete and checked; English by default. */
46
- export class ClaimWords {
47
- static readonly PUBLIC = [
48
- 'published',
49
- 'released',
50
- 'deployed',
51
- 'is live',
52
- 'went live',
53
- 'now live',
54
- ];
55
- static readonly DONE = [
56
- 'all tests pass',
57
- 'tests pass',
58
- 'tests are passing',
59
- 'everything passes',
60
- 'all checks pass',
61
- 'all green',
62
- 'build passes',
63
- 'lint is clean',
64
- 'gates pass',
65
- ];
66
- /** A sentence with one of these is not a claim: it denies, asks, or speaks of what is not yet so. */
67
- static readonly NEGATIONS = [
68
- 'not',
69
- 'no',
70
- 'nothing',
71
- 'never',
72
- 'yet',
73
- 'whether',
74
- 'if',
75
- 'unless',
76
- 'until',
77
- 'when',
78
- 'once',
79
- 'will',
80
- 'would',
81
- 'should',
82
- 'could',
83
- 'might',
84
- 'unpublished',
85
- 'unreleased',
86
- "n't",
87
- ];
88
- }
@@ -1,5 +0,0 @@
1
- export * from './constants.ts';
2
- export * from './classify.ts';
3
- export * from './state.ts';
4
- export * from './loop.ts';
5
- export * from './claims.ts';
@@ -1,48 +0,0 @@
1
- import { SignalConstants } from './constants.ts';
2
- import type { ISignalEvent } from './state.ts';
3
-
4
- export class SignalLoop {
5
- /**
6
- * What the last calls look like when an agent is going round in circles: the same call three times within
7
- * a minute, two calls alternating for three rounds, or one call failing again and again. `undefined` when nothing looks stuck.
8
- */
9
- static loopOf(opts: { events: ISignalEvent[] }): string | undefined {
10
- const { events } = opts;
11
- const last = events.slice(-SignalConstants.SAME_CALL_LIMIT);
12
- const first = last[0];
13
-
14
- if (
15
- first !== undefined &&
16
- last.length === SignalConstants.SAME_CALL_LIMIT &&
17
- last.every((event) => event.key === first.key) &&
18
- (last.at(-1)?.at ?? 0) - first.at < SignalConstants.POLL_WINDOW_MS
19
- ) {
20
- return `the same ${first.tool} call ${SignalConstants.SAME_CALL_LIMIT} times in a row`;
21
- }
22
-
23
- const cycle = events.slice(-SignalConstants.ALTERNATION_LENGTH);
24
- const [one, two] = cycle;
25
-
26
- if (
27
- cycle.length === SignalConstants.ALTERNATION_LENGTH &&
28
- one !== undefined &&
29
- two !== undefined &&
30
- one.key !== two.key &&
31
- cycle.every((event, index) => event.key === (index % 2 === 0 ? one.key : two.key))
32
- ) {
33
- return `${one.tool} and ${two.tool} calls alternating without progress`;
34
- }
35
-
36
- const recent = events.slice(-SignalConstants.FAILURE_WINDOW);
37
-
38
- for (const key of new Set(recent.map((event) => event.key))) {
39
- const failures = recent.filter((event) => event.key === key && !event.isOk);
40
-
41
- if (failures.length >= SignalConstants.FAILURE_LIMIT) {
42
- return `${failures[0]?.tool ?? 'a tool'} failing ${SignalConstants.FAILURE_LIMIT} times with the same input in the last ${SignalConstants.FAILURE_WINDOW} calls`;
43
- }
44
- }
45
-
46
- return undefined;
47
- }
48
- }