@venizia/vulcan 0.4.9-0 → 0.4.9-2

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 (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -3,11 +3,11 @@ import { isAbsolute, resolve } from 'node:path';
3
3
  import { HookConstants } from './common/index.ts';
4
4
  import { TrustStates } from './common/index.ts';
5
5
  import type { IHookCommand, IReadOnlyScript, IWriteCheck, IWriteHit } from './common/index.ts';
6
- import { commandTextsOf } from './command-view.ts';
7
- import { forHost } from './decision.ts';
6
+ import { CommandView } from './command-view.ts';
7
+ import { HookDecision } from './decision.ts';
8
8
  import type { IProjectCommandCheck } from './project-guards.ts';
9
- import { basenameOf, parseShell, programOf } from './shell.ts';
10
- import { listedScriptOf, ReadOnlyScripts, ScriptPaths, trustOf } from './trusted-scripts.ts';
9
+ import { ShellParser } from './shell.ts';
10
+ import { ReadOnlyScripts, ScriptPaths, ScriptTrust } from './trusted-scripts.ts';
11
11
 
12
12
  const MUTATING_VERB = '(?:POST|PUT|PATCH|DELETE)';
13
13
 
@@ -87,163 +87,168 @@ const readScript = (opts: { path: string }): string | undefined =>
87
87
  ? readFileSync(opts.path, 'utf8')
88
88
  : undefined;
89
89
 
90
- /**
91
- * Every reason `command` looks like a write the base rules reserve for a human (V-W-02, V-W-03).
92
- * `trust` lists the scripts the project vouches for (`guard.writes.trustedScripts`, repo-relative, under
93
- * `root`): a listed script that is tracked and identical to HEAD skips the script checks only. The checks
94
- * on the command line itself always run, and a listed script that git says changed is checked like any other.
95
- * `trust.readOnlyScripts` (`guard.writes.trustedScripts` objects, from the manifest) skips them for one call: the
96
- * word right after the script is one of the entry's `readOnly` words and the script is tracked and equals HEAD.
97
- */
98
- export const inspectCommand = (opts: {
99
- command: string;
100
- cwd: string;
101
- trust?: { root: string; scripts: string[]; readOnlyScripts?: IReadOnlyScript[] };
102
- /** The project's own commands (`guard.writes.commands`), checked beside the fixed list. */
103
- extra?: IProjectCommandCheck[];
104
- }): IWriteHit[] => {
105
- // The patterns run on what the command runs, not on its text: a heredoc written to a file, the pattern
106
- // of an `rg` and a commit message are data.
107
- const texts = commandTextsOf({ command: opts.command, withMessages: true });
108
- const checks: IWriteCheck[] = [
109
- ...COMMAND_CHECKS,
110
- ...(opts.extra ?? []).map((check) => ({
111
- rule: check.rule,
112
- what: `${check.what} (this project's pattern)`,
113
- pattern: check.pattern,
114
- })),
115
- ];
116
- const hits: IWriteHit[] = checks
117
- .filter((check) => texts.some((text) => check.pattern.test(text)))
118
- .map((check) => ({
119
- rule: check.rule,
120
- message: check.what,
121
- }));
122
-
123
- const targets = extractScriptTargets({ command: texts.join('\n') });
124
- const entries = opts.trust?.readOnlyScripts ?? [];
125
- // A subcommand counts only when the shell's own words give the same scripts in the same order as the text
126
- // does; any other line (a script named in an argument, a pipe into a runner) is read as a whole.
127
- const invocations = ReadOnlyScripts.extractInvocations({ command: opts.command });
128
- const isPaired =
129
- invocations.length === targets.length &&
130
- invocations.every((invocation, index) => invocation.script === targets[index]);
131
- const hasMoving = texts.some((text) =>
132
- parseShell({ command: text }).some((command) =>
133
- ReadOnlyScripts.MOVING_COMMANDS.has(basenameOf({ word: programOf({ command }).name })),
134
- ),
135
- );
136
-
137
- for (const [index, target] of targets.entries()) {
138
- const sources = scriptPathsOf({ target, cwd: opts.cwd })
139
- .map((path) => readScript({ path }))
140
- .filter((text): text is string => text !== undefined);
90
+ const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
91
+ typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
141
92
 
142
- if (sources.length === 0) {
143
- continue;
144
- }
93
+ export class WriteGuard {
94
+ /**
95
+ * Every reason `command` looks like a write the base rules reserve for a human (V-W-02, V-W-03).
96
+ * `trust` lists the scripts the project vouches for (`guard.writes.trustedScripts`, repo-relative, under
97
+ * `root`): a listed script that is tracked and identical to HEAD skips the script checks only. The checks
98
+ * on the command line itself always run, and a listed script that git says changed is checked like any other.
99
+ * `trust.readOnlyScripts` (`guard.writes.trustedScripts` objects, from the manifest) skips them for one call: the
100
+ * word right after the script is one of the entry's `readOnly` words and the script is tracked and equals HEAD.
101
+ */
102
+ static inspectCommand(opts: {
103
+ command: string;
104
+ cwd: string;
105
+ trust?: { root: string; scripts: string[]; readOnlyScripts?: IReadOnlyScript[] };
106
+ /** The project's own commands (`guard.writes.commands`), checked beside the fixed list. */
107
+ extra?: IProjectCommandCheck[];
108
+ }): IWriteHit[] {
109
+ // The patterns run on what the command runs, not on its text: a heredoc written to a file, the pattern
110
+ // of an `rg` and a commit message are data.
111
+ const texts = CommandView.commandTextsOf({ command: opts.command, withMessages: true });
112
+ const checks: IWriteCheck[] = [
113
+ ...COMMAND_CHECKS,
114
+ ...(opts.extra ?? []).map((check) => ({
115
+ rule: check.rule,
116
+ what: `${check.what} (this project's pattern)`,
117
+ pattern: check.pattern,
118
+ })),
119
+ ];
120
+ const hits: IWriteHit[] = checks
121
+ .filter((check) => texts.some((text) => check.pattern.test(text)))
122
+ .map((check) => ({
123
+ rule: check.rule,
124
+ message: check.what,
125
+ }));
126
+
127
+ const targets = extractScriptTargets({ command: texts.join('\n') });
128
+ const entries = opts.trust?.readOnlyScripts ?? [];
129
+ // A subcommand counts only when the shell's own words give the same scripts in the same order as the text
130
+ // does; any other line (a script named in an argument, a pipe into a runner) is read as a whole.
131
+ const invocations = ReadOnlyScripts.extractInvocations({ command: opts.command });
132
+ const isPaired =
133
+ invocations.length === targets.length &&
134
+ invocations.every((invocation, index) => invocation.script === targets[index]);
135
+ const hasMoving = texts.some((text) =>
136
+ ShellParser.parse({ command: text }).some((command) =>
137
+ ReadOnlyScripts.MOVING_COMMANDS.has(
138
+ ShellParser.basenameOf({ word: ShellParser.programOf({ command }).name }),
139
+ ),
140
+ ),
141
+ );
145
142
 
146
- const subcommand = isPaired ? invocations[index]?.subcommand : undefined;
147
- // After a `cd` the hook does not know the folder a relative script word is from, so no entry covers it.
148
- const isFromUnknownFolder =
149
- !isAbsolute(target) && (isPaired ? invocations[index]?.moved === true : hasMoving);
150
- // An entry covers the word only when both spellings of it (see `scriptPathsOf`) name that same entry.
151
- const covered = (lookup: (spelling: { target: string }) => string | undefined) => {
152
- const asWritten = lookup({ target });
153
-
154
- return asWritten === lookup({ target: resolve(opts.cwd, target) }) ? asWritten : undefined;
155
- };
156
- const trusted = opts.trust;
157
- const listed =
158
- trusted === undefined || isFromUnknownFolder
159
- ? undefined
160
- : (covered((spelling) =>
161
- listedScriptOf({
162
- target: spelling.target,
163
- cwd: opts.cwd,
164
- root: trusted.root,
165
- scripts: trusted.scripts,
166
- }),
167
- ) ??
168
- (subcommand === undefined
169
- ? undefined
170
- : covered((spelling) =>
171
- ReadOnlyScripts.find({
172
- target: spelling.target,
173
- subcommand,
174
- cwd: opts.cwd,
175
- root: trusted.root,
176
- entries,
177
- }),
178
- )));
179
- const trust =
180
- listed === undefined || opts.trust === undefined
181
- ? undefined
182
- : trustOf({ root: opts.trust.root, script: listed });
183
-
184
- if (trust?.state === TrustStates.TRUSTED) {
185
- continue;
143
+ for (const [index, target] of targets.entries()) {
144
+ const sources = scriptPathsOf({ target, cwd: opts.cwd })
145
+ .map((path) => readScript({ path }))
146
+ .filter((text): text is string => text !== undefined);
147
+
148
+ if (sources.length === 0) {
149
+ continue;
150
+ }
151
+
152
+ const subcommand = isPaired ? invocations[index]?.subcommand : undefined;
153
+ // After a `cd` the hook does not know the folder a relative script word is from, so no entry covers it.
154
+ const isFromUnknownFolder =
155
+ !isAbsolute(target) && (isPaired ? invocations[index]?.moved === true : hasMoving);
156
+ // An entry covers the word only when both spellings of it (see `scriptPathsOf`) name that same entry.
157
+ const covered = (lookup: (spelling: { target: string }) => string | undefined) => {
158
+ const asWritten = lookup({ target });
159
+
160
+ return asWritten === lookup({ target: resolve(opts.cwd, target) }) ? asWritten : undefined;
161
+ };
162
+ const trusted = opts.trust;
163
+ const listed =
164
+ trusted === undefined || isFromUnknownFolder
165
+ ? undefined
166
+ : (covered((spelling) =>
167
+ ScriptTrust.listedOf({
168
+ target: spelling.target,
169
+ cwd: opts.cwd,
170
+ root: trusted.root,
171
+ scripts: trusted.scripts,
172
+ }),
173
+ ) ??
174
+ (subcommand === undefined
175
+ ? undefined
176
+ : covered((spelling) =>
177
+ ReadOnlyScripts.find({
178
+ target: spelling.target,
179
+ subcommand,
180
+ cwd: opts.cwd,
181
+ root: trusted.root,
182
+ entries,
183
+ }),
184
+ )));
185
+ const trust =
186
+ listed === undefined || opts.trust === undefined
187
+ ? undefined
188
+ : ScriptTrust.trustOf({ root: opts.trust.root, script: listed });
189
+
190
+ if (trust?.state === TrustStates.TRUSTED) {
191
+ continue;
192
+ }
193
+
194
+ for (const check of SCRIPT_CHECKS.filter((scriptCheck) =>
195
+ sources.some((text) => scriptCheck.pattern.test(text)),
196
+ )) {
197
+ hits.push({
198
+ rule: check.rule,
199
+ message: `${target} looks like it is ${check.what}${trust === undefined ? '' : ` (listed in guard.writes.trustedScripts, but not trusted: ${trust.reason})`}`,
200
+ });
201
+ }
186
202
  }
187
203
 
188
- for (const check of SCRIPT_CHECKS.filter((scriptCheck) =>
189
- sources.some((text) => scriptCheck.pattern.test(text)),
190
- )) {
191
- hits.push({
192
- rule: check.rule,
193
- message: `${target} looks like it is ${check.what}${trust === undefined ? '' : ` (listed in guard.writes.trustedScripts, but not trusted: ${trust.reason})`}`,
194
- });
195
- }
204
+ return hits;
196
205
  }
197
206
 
198
- return hits;
199
- };
207
+ /** The Bash command and cwd from the hook's JSON; `undefined` when it is not what Claude Code sends. */
208
+ static parseHookCommand(opts: { text: string }): IHookCommand | undefined {
209
+ let payload: unknown;
200
210
 
201
- const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
202
- typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
211
+ try {
212
+ payload = JSON.parse(opts.text);
213
+ } catch (error) {
214
+ console.error(
215
+ `[WriteGuard.parseHookCommand] unreadable hook input - letting the command through | ${error instanceof Error ? error.message : String(error)}`,
216
+ );
203
217
 
204
- /** The Bash command and cwd from the hook's JSON; `undefined` when it is not what Claude Code sends. */
205
- export const parseHookCommand = (opts: { text: string }): IHookCommand | undefined => {
206
- let payload: unknown;
218
+ return undefined;
219
+ }
207
220
 
208
- try {
209
- payload = JSON.parse(opts.text);
210
- } catch (error) {
211
- console.error(
212
- `[parseHookCommand] unreadable hook input - letting the command through | ${error instanceof Error ? error.message : String(error)}`,
213
- );
221
+ const holder = { value: payload };
214
222
 
215
- return undefined;
216
- }
223
+ if (!isRecord(holder)) {
224
+ return undefined;
225
+ }
217
226
 
218
- const holder = { value: payload };
227
+ // The wire names are snake_case; they stay behind string-literal access here, at the boundary (V-C-14).
228
+ const toolInput = { value: holder.value['tool_input'] };
229
+ const command = isRecord(toolInput) ? toolInput.value['command'] : undefined;
230
+ const cwd = holder.value['cwd'];
219
231
 
220
- if (!isRecord(holder)) {
221
- return undefined;
232
+ return typeof command === 'string' && command !== ''
233
+ ? { command, cwd: typeof cwd === 'string' ? cwd : undefined }
234
+ : undefined;
222
235
  }
223
236
 
224
- // The wire names are snake_case; they stay behind string-literal access here, at the boundary (V-C-14).
225
- const toolInput = { value: holder.value['tool_input'] };
226
- const command = isRecord(toolInput) ? toolInput.value['command'] : undefined;
227
- const cwd = holder.value['cwd'];
228
-
229
- return typeof command === 'string' && command !== ''
230
- ? { command, cwd: typeof cwd === 'string' ? cwd : undefined }
231
- : undefined;
232
- };
233
-
234
- export const buildGuardDecision = (opts: { hits: IWriteHit[] }) =>
235
- forHost({
236
- output: {
237
- hookSpecificOutput: {
238
- hookEventName: HookConstants.PRE_TOOL_USE,
239
- permissionDecision: HookConstants.GUARD_DECISION,
240
- permissionDecisionReason: [
241
- `This command looks like ${opts.hits.length === 1 ? 'an action' : 'actions'} the base rules reserve for a human:`,
242
- ...opts.hits.map((hit) => ` - ${hit.rule}: ${hit.message}`),
243
- '',
244
- 'The rules reject "it is only dev", "it is only a test row" and "it is reversible".',
245
- 'Produce the script, the SQL or the manifest and hand it over instead of running it.',
246
- ].join('\n'),
237
+ static buildDecision(opts: { hits: IWriteHit[] }) {
238
+ return HookDecision.forHost({
239
+ output: {
240
+ hookSpecificOutput: {
241
+ hookEventName: HookConstants.PRE_TOOL_USE,
242
+ permissionDecision: HookConstants.GUARD_DECISION,
243
+ permissionDecisionReason: [
244
+ `This command looks like ${opts.hits.length === 1 ? 'an action' : 'actions'} the base rules reserve for a human:`,
245
+ ...opts.hits.map((hit) => ` - ${hit.rule}: ${hit.message}`),
246
+ '',
247
+ 'The rules reject "it is only dev", "it is only a test row" and "it is reversible".',
248
+ 'Produce the script, the SQL or the manifest and hand it over instead of running it.',
249
+ ].join('\n'),
250
+ },
247
251
  },
248
- },
249
- });
252
+ });
253
+ }
254
+ }
@@ -1,19 +1,16 @@
1
- import { loadConfig } from '../config/index.ts';
1
+ import { ConfigLoader } from '../config/index.ts';
2
2
  import {
3
- checkOwnerShape,
3
+ OwnerShape,
4
4
  OWNER_SCHEMA,
5
5
  OwnerEnforcement,
6
- isOwnerReplyOff,
7
- readLastClasses,
8
- readProfile,
9
- markBlocked,
10
- recordReply,
11
- wasBlockedRecently,
12
- resolveOwnerView,
6
+ ReplySwitch,
7
+ ViolationLog,
8
+ OwnerProfile,
9
+ OwnerView,
13
10
  ShapeClasses,
14
11
  } from '../owner/index.ts';
15
12
  import type { IOwnerView } from '../owner/index.ts';
16
- import { checkClaims, readSignals, startTurn } from '../signals/index.ts';
13
+ import { ReplyClaims, SignalState } from '../signals/index.ts';
17
14
 
18
15
  /** What to do about each class, in the words of the block message. */
19
16
  const FIXES: Record<string, string> = {
@@ -34,129 +31,132 @@ const FIXES: Record<string, string> = {
34
31
 
35
32
  /** The owner's view of the project in `projectRoot`; a project whose config cannot load gets the defaults. */
36
33
  const loadOwnerView = async (opts: { projectRoot: string }): Promise<IOwnerView> => {
37
- const loaded = await loadConfig({ root: opts.projectRoot });
38
- const profile = readProfile({ root: opts.projectRoot });
34
+ const loaded = await ConfigLoader.load({ root: opts.projectRoot });
35
+ const profile = OwnerProfile.read({ root: opts.projectRoot });
39
36
 
40
- return resolveOwnerView({
37
+ return OwnerView.resolve({
41
38
  owner: loaded.ok ? loaded.config.owner : OWNER_SCHEMA.parse(undefined),
42
39
  profile: profile.ok ? profile.profile : undefined,
43
40
  });
44
41
  };
45
42
 
46
- /**
47
- * The Stop hook's answer for the last reply: it is checked and recorded (classes and date only), and
48
- * only under `block`, once per message and only for a structural fault, is it sent back to be restated.
49
- * Anything it cannot read passes: it never stops a session by failing. A session started with
50
- * `VULCAN_OWNER_REPLY=off` (a session whose reader is an agent) is not checked, logged or blocked at all.
51
- */
52
- export const buildStopOutput = async (opts: {
53
- projectRoot: string;
54
- input: unknown;
55
- /** The environment of the session; `VULCAN_OWNER_REPLY=off` exempts it. */
56
- env?: Record<string, string | undefined>;
57
- }): Promise<Record<string, unknown> | undefined> => {
58
- const { input } = opts;
59
-
60
- if (isOwnerReplyOff({ env: opts.env ?? process.env })) {
61
- return undefined;
43
+ export class OwnerReply {
44
+ /**
45
+ * The Stop hook's answer for the last reply: it is checked and recorded (classes and date only), and
46
+ * only under `block`, once per message and only for a structural fault, is it sent back to be restated.
47
+ * Anything it cannot read passes: it never stops a session by failing. A session started with
48
+ * `VULCAN_OWNER_REPLY=off` (a session whose reader is an agent) is not checked, logged or blocked at all.
49
+ */
50
+ static async buildStopOutput(opts: {
51
+ projectRoot: string;
52
+ input: unknown;
53
+ /** The environment of the session; `VULCAN_OWNER_REPLY=off` exempts it. */
54
+ env?: Record<string, string | undefined>;
55
+ }): Promise<Record<string, unknown> | undefined> {
56
+ const { input } = opts;
57
+
58
+ if (ReplySwitch.isOwnerOff({ env: opts.env ?? process.env })) {
59
+ return undefined;
60
+ }
61
+
62
+ if (typeof input !== 'object' || input === null || !('last_assistant_message' in input)) {
63
+ return undefined;
64
+ }
65
+
66
+ const { last_assistant_message: text } = input;
67
+ const isRetry = 'stop_hook_active' in input && input.stop_hook_active === true;
68
+ const session =
69
+ 'session_id' in input && typeof input.session_id === 'string' ? input.session_id : '';
70
+ const view = await loadOwnerView({ projectRoot: opts.projectRoot });
71
+
72
+ if (typeof text !== 'string' || view.enforce === OwnerEnforcement.OFF) {
73
+ return undefined;
74
+ }
75
+
76
+ const result = OwnerShape.check({ text, view });
77
+ // A claim is checked on every reply, a short one too: "Published." is the shortest wrong one.
78
+ const claims = ReplyClaims.check({
79
+ text,
80
+ state: SignalState.read({ root: opts.projectRoot, session }),
81
+ publicWords: view.claimWords.public,
82
+ doneWords: view.claimWords.done,
83
+ });
84
+ const classes = [...result.classes, ...claims];
85
+
86
+ // Every reply updates the note the next prompt reads, an exempt short one too; a write that fails never
87
+ // costs the decision below.
88
+ try {
89
+ ViolationLog.recordReply({ root: opts.projectRoot, classes, session });
90
+ } catch {
91
+ // The log is advisory.
92
+ }
93
+
94
+ if (!result.isChecked) {
95
+ return undefined;
96
+ }
97
+
98
+ const structural = result.classes.filter((name) => ShapeClasses.isStructural(name));
99
+
100
+ if (
101
+ view.enforce !== OwnerEnforcement.BLOCK ||
102
+ isRetry ||
103
+ structural.length === 0 ||
104
+ ViolationLog.wasBlockedRecently({ root: opts.projectRoot, session })
105
+ ) {
106
+ return undefined;
107
+ }
108
+
109
+ try {
110
+ ViolationLog.markBlocked({ root: opts.projectRoot, session });
111
+ } catch {
112
+ // Without the note the stop_hook_active flag is the only guard against a second block.
113
+ }
114
+
115
+ return {
116
+ decision: 'block',
117
+ reason: [
118
+ 'The reply to the owner breaks the report shape (see "How to answer the owner" in the session rules). Restate it once, in full:',
119
+ ...structural.map((name) => ` - ${name}: ${FIXES[name] ?? name}`),
120
+ ].join('\n'),
121
+ };
62
122
  }
63
123
 
64
- if (typeof input !== 'object' || input === null || !('last_assistant_message' in input)) {
65
- return undefined;
124
+ /**
125
+ * One line added to every prompt while the shape is held: the contract, and the faults of the reply
126
+ * before when it had any. Empty when the shape is not enforced.
127
+ */
128
+ static async buildPromptContract(opts: {
129
+ projectRoot: string;
130
+ /** The session the prompt belongs to; its turn begins here. */
131
+ session?: string;
132
+ /** The environment of the session; `VULCAN_OWNER_REPLY=off` exempts it. */
133
+ env?: Record<string, string | undefined>;
134
+ }): Promise<string> {
135
+ // A new turn begins with this prompt: the notes of the last one are forgotten, whatever is enforced.
136
+ try {
137
+ SignalState.startTurn({ root: opts.projectRoot, session: opts.session ?? '' });
138
+ } catch {
139
+ // The notes are advisory.
140
+ }
141
+
142
+ if (ReplySwitch.isOwnerOff({ env: opts.env ?? process.env })) {
143
+ return '';
144
+ }
145
+
146
+ const view = await loadOwnerView({ projectRoot: opts.projectRoot });
147
+
148
+ if (view.enforce === OwnerEnforcement.OFF) {
149
+ return '';
150
+ }
151
+
152
+ // A claim match is a hint, so it is logged but never said back to the model as a fault of the last reply.
153
+ const last = ViolationLog.readLastClasses({
154
+ root: opts.projectRoot,
155
+ session: opts.session,
156
+ }).filter((name) => ShapeClasses.isValid(name));
157
+
158
+ return last.length === 0
159
+ ? 'Owner reply contract: follow the report shape from the session rules.'
160
+ : `Owner reply contract: follow the report shape from the session rules. Your last reply broke it - ${last.map((name) => FIXES[name] ?? name).join('; ')}.`;
66
161
  }
67
-
68
- const { last_assistant_message: text } = input;
69
- const isRetry = 'stop_hook_active' in input && input.stop_hook_active === true;
70
- const session =
71
- 'session_id' in input && typeof input.session_id === 'string' ? input.session_id : '';
72
- const view = await loadOwnerView({ projectRoot: opts.projectRoot });
73
-
74
- if (typeof text !== 'string' || view.enforce === OwnerEnforcement.OFF) {
75
- return undefined;
76
- }
77
-
78
- const result = checkOwnerShape({ text, view });
79
- // A claim is checked on every reply, a short one too: "Published." is the shortest wrong one.
80
- const claims = checkClaims({
81
- text,
82
- state: readSignals({ root: opts.projectRoot, session }),
83
- publicWords: view.claimWords.public,
84
- doneWords: view.claimWords.done,
85
- });
86
- const classes = [...result.classes, ...claims];
87
-
88
- // Every reply updates the note the next prompt reads, an exempt short one too; a write that fails never
89
- // costs the decision below.
90
- try {
91
- recordReply({ root: opts.projectRoot, classes, session });
92
- } catch {
93
- // The log is advisory.
94
- }
95
-
96
- if (!result.isChecked) {
97
- return undefined;
98
- }
99
-
100
- const structural = result.classes.filter((name) => ShapeClasses.isStructural(name));
101
-
102
- if (
103
- view.enforce !== OwnerEnforcement.BLOCK ||
104
- isRetry ||
105
- structural.length === 0 ||
106
- wasBlockedRecently({ root: opts.projectRoot, session })
107
- ) {
108
- return undefined;
109
- }
110
-
111
- try {
112
- markBlocked({ root: opts.projectRoot, session });
113
- } catch {
114
- // Without the note the stop_hook_active flag is the only guard against a second block.
115
- }
116
-
117
- return {
118
- decision: 'block',
119
- reason: [
120
- 'The reply to the owner breaks the report shape (see "How to answer the owner" in the session rules). Restate it once, in full:',
121
- ...structural.map((name) => ` - ${name}: ${FIXES[name] ?? name}`),
122
- ].join('\n'),
123
- };
124
- };
125
-
126
- /**
127
- * One line added to every prompt while the shape is held: the contract, and the faults of the reply
128
- * before when it had any. Empty when the shape is not enforced.
129
- */
130
- export const buildPromptContract = async (opts: {
131
- projectRoot: string;
132
- /** The session the prompt belongs to; its turn begins here. */
133
- session?: string;
134
- /** The environment of the session; `VULCAN_OWNER_REPLY=off` exempts it. */
135
- env?: Record<string, string | undefined>;
136
- }): Promise<string> => {
137
- // A new turn begins with this prompt: the notes of the last one are forgotten, whatever is enforced.
138
- try {
139
- startTurn({ root: opts.projectRoot, session: opts.session ?? '' });
140
- } catch {
141
- // The notes are advisory.
142
- }
143
-
144
- if (isOwnerReplyOff({ env: opts.env ?? process.env })) {
145
- return '';
146
- }
147
-
148
- const view = await loadOwnerView({ projectRoot: opts.projectRoot });
149
-
150
- if (view.enforce === OwnerEnforcement.OFF) {
151
- return '';
152
- }
153
-
154
- // A claim match is a hint, so it is logged but never said back to the model as a fault of the last reply.
155
- const last = readLastClasses({ root: opts.projectRoot, session: opts.session }).filter((name) =>
156
- ShapeClasses.isValid(name),
157
- );
158
-
159
- return last.length === 0
160
- ? 'Owner reply contract: follow the report shape from the session rules.'
161
- : `Owner reply contract: follow the report shape from the session rules. Your last reply broke it - ${last.map((name) => FIXES[name] ?? name).join('; ')}.`;
162
- };
162
+ }