@venizia/vulcan 0.4.5 → 0.4.6

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 (51) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/checks/wiki-anchors.ts +8 -0
  4. package/base/checks/wiki-source-links.ts +8 -0
  5. package/base/hooks/guard-git.ts +9 -2
  6. package/base/hooks/guard-writes.ts +4 -0
  7. package/base/hooks/session-start.ts +14 -4
  8. package/base/make/vulcan.mk +12 -1
  9. package/base/references/delegation-brief.md +5 -4
  10. package/base/rules.md +2 -2
  11. package/base/skills/docs-writing/SKILL.md +1 -1
  12. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  13. package/base/skills/knowledge-sync/SKILL.md +1 -1
  14. package/base/skills/plan-a-change/SKILL.md +1 -1
  15. package/base/skills/report-back/SKILL.md +1 -1
  16. package/base/skills/retro/SKILL.md +1 -1
  17. package/base/skills/review-a-change/SKILL.md +1 -1
  18. package/base/skills/ship/SKILL.md +1 -1
  19. package/base/skills/visualize-work/SKILL.md +33 -11
  20. package/base/skills/visualize-work/references/spec.md +77 -12
  21. package/package.json +4 -4
  22. package/src/config/schema.ts +58 -4
  23. package/src/doctor/checks.ts +29 -1
  24. package/src/doctor/runner.ts +2 -0
  25. package/src/hooks/common/constants.ts +5 -0
  26. package/src/hooks/guard-git.ts +22 -2
  27. package/src/hooks/guard-outside.ts +20 -3
  28. package/src/hooks/guard-writes.ts +17 -6
  29. package/src/hooks/index.ts +2 -0
  30. package/src/hooks/project-guards.ts +123 -0
  31. package/src/hooks/project-tmp.ts +36 -0
  32. package/src/hooks/session-digest.ts +5 -0
  33. package/src/manifest/render.ts +38 -0
  34. package/src/sync/claude-launch.ts +48 -0
  35. package/src/sync/index.ts +1 -0
  36. package/src/sync/local-choice.ts +2 -0
  37. package/src/visualize/assets.ts +195 -54
  38. package/src/visualize/charts.ts +235 -0
  39. package/src/visualize/constants.ts +106 -1
  40. package/src/visualize/diagrams.ts +224 -0
  41. package/src/visualize/icons.ts +28 -0
  42. package/src/visualize/layout.ts +58 -8
  43. package/src/visualize/page.ts +152 -146
  44. package/src/visualize/schema.ts +246 -0
  45. package/src/visualize/sections.ts +370 -0
  46. package/src/visualize/validate.ts +100 -7
  47. package/src/wiki/anchors.ts +118 -0
  48. package/src/wiki/command.ts +110 -0
  49. package/src/wiki/constants.ts +30 -0
  50. package/src/wiki/index.ts +4 -0
  51. package/src/wiki/source-links.ts +186 -0
@@ -840,7 +840,7 @@ export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
840
840
  const FMT_SECTION_ADVICE =
841
841
  'add a [fmt] section (printWidth = 100, singleQuote = true, arrowParens = "always", flavor = "oxfmt"): without it bun fmt formats with Bun\'s defaults, not the shared style';
842
842
  const FMT_FLAVOR_ADVICE =
843
- 'without it bun fmt formats like Prettier when oxfmt is not a dependency, and the output changes';
843
+ 'without it bun fmt uses its default style when oxfmt is not a dependency, and the output changes';
844
844
  const OXFMT_LOADED_ADVICE =
845
845
  'bun fmt loads it and it overrides the [fmt] section of bunfig.toml - delete it, or move its settings to [fmt]';
846
846
 
@@ -1205,6 +1205,34 @@ export const checkStaleTrustedScripts = (opts: ICheckContext): IViolation[] =>
1205
1205
  : [];
1206
1206
  });
1207
1207
 
1208
+ /**
1209
+ * The commands and push targets the project adds to guard-writes and guard-git, one note each: so the
1210
+ * guards' reach beyond their own list is visible where a person looks, with the rule and the pattern.
1211
+ */
1212
+ export const checkGuardPatterns = (opts: ICheckContext): IViolation[] => {
1213
+ const { commands } = opts.config.guard.writes;
1214
+ const { askPush } = opts.config.guard.git;
1215
+
1216
+ return [
1217
+ ...commands.map((command) =>
1218
+ createViolation({
1219
+ check: DoctorChecks.GUARDS,
1220
+ file: opts.configFile,
1221
+ message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
1222
+ }),
1223
+ ),
1224
+ ...(askPush.length === 0
1225
+ ? []
1226
+ : [
1227
+ createViolation({
1228
+ check: DoctorChecks.GUARDS,
1229
+ file: opts.configFile,
1230
+ message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
1231
+ }),
1232
+ ]),
1233
+ ];
1234
+ };
1235
+
1208
1236
  export const checkLocalSize = (opts: ICheckContext): IViolation[] => {
1209
1237
  const entries = scanLocal({ root: opts.root });
1210
1238
  const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
@@ -22,6 +22,7 @@ import {
22
22
  checkTrustedScripts,
23
23
  checkHooks,
24
24
  checkLayout,
25
+ checkGuardPatterns,
25
26
  checkLocalWorkspace,
26
27
  checkMake,
27
28
  checkOutsideWorktrees,
@@ -97,6 +98,7 @@ export const runDoctorNotes = async (opts: {
97
98
  ...checkAppScripts(context),
98
99
  ...checkAtlasBlock(context),
99
100
  ...checkLocalSize(context),
101
+ ...checkGuardPatterns(context),
100
102
  ...checkReplyShape(context),
101
103
  ...checkOwnerReplySwitch({ env: opts.env ?? process.env }),
102
104
  ...checkTrustedScripts(context),
@@ -58,6 +58,11 @@ export class HookConstants {
58
58
  static readonly MAX_QUERIES = 4;
59
59
  /** Branches no agent deletes or force-pushes (V-W-06). */
60
60
  static readonly PROTECTED_BRANCHES = new Set(['develop', 'main']);
61
+ /**
62
+ * Where a session's temporary files go, from the project root: `ProjectLayout.LOCAL_DIRECTORY` and `tmp`.
63
+ * Spelt out here because the blocking hooks import nothing that reads the package (a test holds the two equal).
64
+ */
65
+ static readonly PROJECT_TMP = '.agents/local/tmp';
61
66
  /** Set to `off` to switch the guards off for a session; the hooks then pass every call. */
62
67
  static readonly KILL_SWITCH_ENV = 'VULCAN_GUARDS';
63
68
  static readonly KILL_SWITCH_OFF = 'off';
@@ -3,6 +3,7 @@ import { basenameOf, parseShellChecked, programOf } from './shell.ts';
3
3
  import type { ISimpleCommand } from './shell.ts';
4
4
  import { GuardDecisions, HookConstants } from './common/index.ts';
5
5
  import type { IGitHit, IGitRunner } from './common/index.ts';
6
+ import { matchesBranch } from './project-guards.ts';
6
7
 
7
8
  /** `git` and `gh` read-only queries the guard makes; `undefined` when the tool is missing, slow or fails. */
8
9
  export const runQuery: IGitRunner = (opts) => {
@@ -57,6 +58,7 @@ const inspectPush = (opts: {
57
58
  rest: string[];
58
59
  cwd: string | undefined;
59
60
  run: IGitRunner;
61
+ askPush: string[];
60
62
  }): IGitHit[] => {
61
63
  const flags = opts.rest.filter((word) => word.startsWith('-') && word !== '-');
62
64
  const positional = opts.rest.filter((word) => !word.startsWith('-'));
@@ -97,6 +99,21 @@ const inspectPush = (opts: {
97
99
  }
98
100
  }
99
101
 
102
+ // A target the project lists asks even for a plain push; a hit already made says the push needs a human.
103
+ if (hits.length === 0 && !deleting) {
104
+ for (const name of targets) {
105
+ const branch = name.replace(/^\+/, '').replace(/^refs\/heads\//, '');
106
+
107
+ if (matchesBranch({ name: branch, patterns: opts.askPush })) {
108
+ hits.push({
109
+ decision: GuardDecisions.ASK,
110
+ rule: 'V-W-06',
111
+ message: `pushing to '${branch}', a target this project lists in guard.git.askPush`,
112
+ });
113
+ }
114
+ }
115
+ }
116
+
100
117
  if (flags.includes('--mirror')) {
101
118
  hits.push({
102
119
  decision: GuardDecisions.ASK,
@@ -229,6 +246,7 @@ const inspectOne = (opts: {
229
246
  command: ISimpleCommand;
230
247
  cwd: string | undefined;
231
248
  run: IGitRunner;
249
+ askPush: string[];
232
250
  }): IGitHit[] => {
233
251
  const program = programOf({ command: opts.command });
234
252
  const name = basenameOf({ word: program.name });
@@ -245,7 +263,7 @@ const inspectOne = (opts: {
245
263
  const cwd = call.dir ?? opts.cwd;
246
264
 
247
265
  if (call.sub === 'push') {
248
- return inspectPush({ rest: call.rest, cwd, run: opts.run });
266
+ return inspectPush({ rest: call.rest, cwd, run: opts.run, askPush: opts.askPush });
249
267
  }
250
268
 
251
269
  if (call.sub === 'branch') {
@@ -282,6 +300,8 @@ export const inspectGit = (opts: {
282
300
  command: string;
283
301
  cwd: string | undefined;
284
302
  run?: IGitRunner;
303
+ /** Branches (names, `*` allowed) a plain `git push` asks about: `guard.git.askPush`. */
304
+ askPush?: string[];
285
305
  }): IGitHit[] => {
286
306
  const parsed = parseShellChecked({ command: opts.command });
287
307
  const run = opts.run ?? runQuery;
@@ -301,7 +321,7 @@ export const inspectGit = (opts: {
301
321
  return run(call);
302
322
  };
303
323
  const hits = parsed.commands.flatMap((command) =>
304
- inspectOne({ command, cwd: opts.cwd, run: limited }),
324
+ inspectOne({ command, cwd: opts.cwd, run: limited, askPush: opts.askPush ?? [] }),
305
325
  );
306
326
 
307
327
  // Part of the line was not read: never an allow.
@@ -4,6 +4,7 @@ import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
4
4
  import { basenameOf, parseShellChecked, programOf } from './shell.ts';
5
5
  import type { ISimpleCommand } from './shell.ts';
6
6
  import { HookConstants } from './common/index.ts';
7
+ import { projectTmpOf } from './project-tmp.ts';
7
8
  import type { IManifestHookInput, IOutsideHit } from './common/index.ts';
8
9
 
9
10
  const FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
@@ -238,7 +239,7 @@ const gitTargets = (opts: { rest: string[]; base: string; dir: string | undefine
238
239
  };
239
240
 
240
241
  /** The words a simple command would create or write, with a name for what writes them. */
241
- const targetsOf = (opts: { command: ISimpleCommand; base: string }): ITarget[] => {
242
+ const targetsOf = (opts: { command: ISimpleCommand; base: string; tmp: string }): ITarget[] => {
242
243
  const program = programOf({ command: opts.command });
243
244
  const name = basenameOf({ word: program.name });
244
245
  const { args } = program;
@@ -314,7 +315,7 @@ const targetsOf = (opts: { command: ISimpleCommand; base: string }): ITarget[] =
314
315
  if (directory !== undefined) {
315
316
  add(directory, 'mktemp creates a temporary file');
316
317
  } else if (inTmpdir || template === undefined) {
317
- add(tmpdir(), 'mktemp creates a file in the system temp directory');
318
+ add(opts.tmp, 'mktemp creates a file in the system temp directory');
318
319
  } else {
319
320
  add(template, 'mktemp creates a temporary file');
320
321
  }
@@ -327,6 +328,21 @@ const targetsOf = (opts: { command: ISimpleCommand; base: string }): ITarget[] =
327
328
  return targets;
328
329
  };
329
330
 
331
+ /**
332
+ * The folder a bare `mktemp` uses in the command: the `TMPDIR` this hook runs with (Claude Code started
333
+ * with the launch file or the variables), else the project's own folder when Claude Code's session-start
334
+ * hook exports it (`CLAUDE_PROJECT_DIR` is set only by Claude Code), else the system temp directory.
335
+ */
336
+ const commandTmpdirOf = (opts: { env: TEnvironment; projectRoot: string }): string => {
337
+ if (opts.env.TMPDIR !== undefined && opts.env.TMPDIR !== '') {
338
+ return opts.env.TMPDIR;
339
+ }
340
+
341
+ return opts.env.CLAUDE_PROJECT_DIR === undefined
342
+ ? tmpdir()
343
+ : projectTmpOf({ root: opts.projectRoot });
344
+ };
345
+
330
346
  /**
331
347
  * Every file, worktree, clone or temp file `input` would create outside the project. Files a package
332
348
  * manager, a runtime or the agent tool manage themselves are allowed (`toolOwnedPaths`, extending the
@@ -350,6 +366,7 @@ export const inspectOutside = (opts: {
350
366
  env,
351
367
  });
352
368
  const start = opts.input.cwd ?? opts.projectRoot;
369
+ const tmp = commandTmpdirOf({ env, projectRoot: opts.projectRoot });
353
370
  const targets: ITarget[] = [];
354
371
 
355
372
  if (FILE_TOOLS.has(opts.input.tool) && opts.input.filePath !== undefined) {
@@ -381,7 +398,7 @@ export const inspectOutside = (opts: {
381
398
  continue;
382
399
  }
383
400
 
384
- targets.push(...targetsOf({ command, base }));
401
+ targets.push(...targetsOf({ command, base, tmp }));
385
402
  }
386
403
  }
387
404
 
@@ -5,6 +5,7 @@ import { TrustStates } from './common/index.ts';
5
5
  import type { IHookCommand, IWriteCheck, IWriteHit } from './common/index.ts';
6
6
  import { commandTextsOf } from './command-view.ts';
7
7
  import { forHost } from './decision.ts';
8
+ import type { IProjectCommandCheck } from './project-guards.ts';
8
9
  import { listedScriptOf, trustOf } from './trusted-scripts.ts';
9
10
 
10
11
  const MUTATING_VERB = '(?:POST|PUT|PATCH|DELETE)';
@@ -87,16 +88,26 @@ export const inspectCommand = (opts: {
87
88
  command: string;
88
89
  cwd: string;
89
90
  trust?: { root: string; scripts: string[] };
91
+ /** The project's own commands (`guard.writes.commands`), checked beside the fixed list. */
92
+ extra?: IProjectCommandCheck[];
90
93
  }): IWriteHit[] => {
91
94
  // The patterns run on what the command runs, not on its text: a heredoc written to a file, the pattern
92
95
  // of an `rg` and a commit message are data.
93
96
  const texts = commandTextsOf({ command: opts.command, withMessages: true });
94
- const hits: IWriteHit[] = COMMAND_CHECKS.filter((check) =>
95
- texts.some((text) => check.pattern.test(text)),
96
- ).map((check) => ({
97
- rule: check.rule,
98
- message: check.what,
99
- }));
97
+ const checks: IWriteCheck[] = [
98
+ ...COMMAND_CHECKS,
99
+ ...(opts.extra ?? []).map((check) => ({
100
+ rule: check.rule,
101
+ what: `${check.what} (this project's pattern)`,
102
+ pattern: check.pattern,
103
+ })),
104
+ ];
105
+ const hits: IWriteHit[] = checks
106
+ .filter((check) => texts.some((text) => check.pattern.test(text)))
107
+ .map((check) => ({
108
+ rule: check.rule,
109
+ message: check.what,
110
+ }));
100
111
 
101
112
  for (const target of extractScriptTargets({ command: texts.join('\n') })) {
102
113
  const source = readScript({ target, cwd: opts.cwd });
@@ -10,6 +10,8 @@ export * from './trusted-scripts.ts';
10
10
  export * from './session-digest.ts';
11
11
  export * from './subagent-card.ts';
12
12
  export * from './owner-reply.ts';
13
+ export * from './project-tmp.ts';
14
+ export * from './project-guards.ts';
13
15
  export * from './remote-hosts.ts';
14
16
  export * from './codex-patch.ts';
15
17
  export * from './shell.ts';
@@ -0,0 +1,123 @@
1
+ import { existsSync, readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+
4
+ /** A command the project says is a database write or a deploy: guard-writes asks on a match. */
5
+ export interface IProjectCommandCheck {
6
+ rule: 'V-W-02' | 'V-W-03';
7
+ what: string;
8
+ pattern: RegExp;
9
+ }
10
+
11
+ /** What the project adds to the guards: the manifest's `guard` block, compiled. */
12
+ export interface IGuardPolicy {
13
+ commands: IProjectCommandCheck[];
14
+ askPush: string[];
15
+ }
16
+
17
+ /** Spelt out: the blocking hooks import nothing that reads the package (a test holds it equal to the manifest's name). */
18
+ export const GUARD_MANIFEST_FILE = '.agents/vulcan.manifest.json';
19
+
20
+ const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
21
+ typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
22
+
23
+ const ruleOf = (opts: { value: unknown }): 'V-W-02' | 'V-W-03' | undefined =>
24
+ opts.value === 'V-W-02' || opts.value === 'V-W-03' ? opts.value : undefined;
25
+
26
+ const note = (opts: { message: string }): void => {
27
+ console.error(`vulcan: [guard] ${opts.message}`);
28
+ };
29
+
30
+ const commandOf = (opts: { value: unknown }): IProjectCommandCheck | undefined => {
31
+ const holder = { value: opts.value };
32
+
33
+ if (!isRecord(holder)) {
34
+ return undefined;
35
+ }
36
+
37
+ const rule = ruleOf({ value: holder.value['rule'] });
38
+ const what = holder.value['what'];
39
+ const source = holder.value['pattern'];
40
+
41
+ if (rule === undefined || typeof what !== 'string' || what === '' || typeof source !== 'string') {
42
+ note({
43
+ message: 'ignoring a guard.writes.commands entry that has no usable rule, what or pattern',
44
+ });
45
+
46
+ return undefined;
47
+ }
48
+
49
+ try {
50
+ return {
51
+ rule,
52
+ what,
53
+ pattern: new RegExp(source, holder.value['ignoreCase'] === true ? 'i' : ''),
54
+ };
55
+ } catch (error) {
56
+ note({
57
+ message: `ignoring the pattern '${source}' of guard.writes.commands (${error instanceof Error ? error.message : String(error)})`,
58
+ });
59
+
60
+ return undefined;
61
+ }
62
+ };
63
+
64
+ /**
65
+ * The commands and push targets a project lists, from the committed manifest (`vulcan sync` renders
66
+ * them from the config), so a hook reads them with no config loader and no zod. A project with no
67
+ * manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
68
+ * stderr, and the others stay.
69
+ */
70
+ export const readGuardPolicy = (opts: { root: string }): IGuardPolicy => {
71
+ const path = join(opts.root, GUARD_MANIFEST_FILE);
72
+ const empty: IGuardPolicy = { commands: [], askPush: [] };
73
+
74
+ if (!existsSync(path)) {
75
+ return empty;
76
+ }
77
+
78
+ let manifest: unknown;
79
+
80
+ try {
81
+ manifest = JSON.parse(readFileSync(path, 'utf8'));
82
+ } catch (error) {
83
+ note({
84
+ message: `the manifest could not be read, so the project's own patterns are off (${error instanceof Error ? error.message : String(error)})`,
85
+ });
86
+
87
+ return empty;
88
+ }
89
+
90
+ const top = { value: manifest };
91
+ const guard = isRecord(top) ? { value: top.value['guard'] } : { value: undefined };
92
+
93
+ if (!isRecord(guard)) {
94
+ return empty;
95
+ }
96
+
97
+ const writes = { value: guard.value['writes'] };
98
+ const git = { value: guard.value['git'] };
99
+ const listed = isRecord(writes) ? writes.value['commands'] : undefined;
100
+ const targets = isRecord(git) ? git.value['askPush'] : undefined;
101
+
102
+ return {
103
+ commands: (Array.isArray(listed) ? listed : []).flatMap((entry) => {
104
+ const check = commandOf({ value: entry });
105
+
106
+ return check === undefined ? [] : [check];
107
+ }),
108
+ askPush: (Array.isArray(targets) ? targets : []).filter(
109
+ (target): target is string => typeof target === 'string' && target !== '',
110
+ ),
111
+ };
112
+ };
113
+
114
+ /** Whether a branch name is one of the listed names; `*` stands for any run of characters, nothing else is special. */
115
+ export const matchesBranch = (opts: { name: string; patterns: string[] }): boolean =>
116
+ opts.patterns.some((pattern) =>
117
+ new RegExp(
118
+ `^${pattern
119
+ .split('*')
120
+ .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
121
+ .join('.*')}$`,
122
+ ).test(opts.name),
123
+ );
@@ -0,0 +1,36 @@
1
+ import { appendFileSync, mkdirSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { HookConstants } from './common/index.ts';
4
+
5
+ /** `<root>/.agents/local/tmp`: where a session's temporary files go, absolute. `vulcan clean` reads its age. */
6
+ export const projectTmpOf = (opts: { root: string }): string =>
7
+ join(opts.root, HookConstants.PROJECT_TMP);
8
+
9
+ /** A word for `sh`, whatever it holds: in single quotes, a quote itself closed, escaped and opened again. */
10
+ const shellQuote = (opts: { text: string }): string => `'${opts.text.replaceAll("'", "'\\''")}'`;
11
+
12
+ /**
13
+ * Makes every Bash command of a Claude Code session run with `TMPDIR` in the project. Claude Code hands a
14
+ * SessionStart hook a file (`CLAUDE_ENV_FILE`) and sources it before each Bash command, so one `export`
15
+ * there is enough: `mktemp`, bun, node and every script a command starts then use the project folder. It
16
+ * does not move Claude Code's own task-output files or an MCP server (those need the launch file), and
17
+ * `TMPDIR` in the project's settings `env` is not applied by Claude Code, which is why this is a hook.
18
+ * Returns whether it wrote; with no file (another agent, a run outside Claude Code) it does nothing. A
19
+ * path with a line break is refused: a line of shell must never be made from a folder name.
20
+ */
21
+ export const exportProjectTmp = (opts: { root: string; envFile: string | undefined }): boolean => {
22
+ if (opts.envFile === undefined || opts.envFile === '') {
23
+ return false;
24
+ }
25
+
26
+ const folder = projectTmpOf({ root: opts.root });
27
+
28
+ if (/[\r\n]/.test(folder)) {
29
+ return false;
30
+ }
31
+
32
+ mkdirSync(folder, { recursive: true });
33
+ appendFileSync(opts.envFile, `export TMPDIR=${shellQuote({ text: folder })}\n`);
34
+
35
+ return true;
36
+ };
@@ -11,6 +11,7 @@ import {
11
11
  resolveOwnerView,
12
12
  } from '../owner/index.ts';
13
13
  import { extractRuleRows, parseRuleIds, readSlots, RuleConstants } from '../rules/index.ts';
14
+ import { projectTmpOf } from './project-tmp.ts';
14
15
 
15
16
  /** A project row whose first cell lists IDs - `| V-W-02, V-W-03 |` - elaborates those base rules. */
16
17
  const ID_LIST_ROW =
@@ -96,6 +97,10 @@ export const buildSessionDigest = async (opts: {
96
97
  ...TABLE_HEADER,
97
98
  ...baseRows.filter((row) => row.startsWith(`| ${RuleConstants.BASE_NAMESPACE}W-`)),
98
99
  '',
100
+ '## Temporary files',
101
+ '',
102
+ `Scratch and temporary files go in \`${projectTmpOf({ root: opts.projectRoot })}\`, never /tmp (V-B-08). In Claude Code every Bash command already runs with \`TMPDIR\` set to it; in any other agent run \`export TMPDIR=${projectTmpOf({ root: opts.projectRoot })}\` first. Remove what you made when the task ends.`,
103
+ '',
99
104
  "## This project's slot choices",
100
105
  '',
101
106
  ...slotRows,
@@ -46,6 +46,40 @@ export const buildBaseRuleHashes = (): Record<string, string> =>
46
46
  }),
47
47
  );
48
48
 
49
+ /** The manifest's `guard` block: what the project adds to guard-writes and guard-git, as data a hook reads without the config. */
50
+ const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<string, unknown> } => {
51
+ const { commands } = opts.config.guard.writes;
52
+ const { askPush } = opts.config.guard.git;
53
+ const block = {
54
+ ...(commands.length === 0
55
+ ? {}
56
+ : {
57
+ writes: {
58
+ commands: commands.map((command) => ({
59
+ rule: command.rule,
60
+ what: command.what,
61
+ pattern: command.pattern,
62
+ ...(command.ignoreCase === true ? { ignoreCase: true } : {}),
63
+ })),
64
+ },
65
+ }),
66
+ ...(askPush.length === 0 ? {} : { git: { askPush } }),
67
+ };
68
+
69
+ return Object.keys(block).length === 0 ? {} : { guard: block };
70
+ };
71
+
72
+ /** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
73
+ const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<string, unknown> } => {
74
+ const keys = opts.config.atlas.index?.keys ?? [];
75
+ const block = {
76
+ ...(keys.length === 0 ? {} : { index: { keys } }),
77
+ ...(opts.config.atlas.prebuilt === false ? { prebuilt: false } : {}),
78
+ };
79
+
80
+ return Object.keys(block).length === 0 ? {} : { atlas: block };
81
+ };
82
+
49
83
  /**
50
84
  * The project manifest (Project Contract v1, C1): data only, rendered from the config with a fixed
51
85
  * key order, so the committed file is byte-stable and a stale one shows as a diff.
@@ -82,6 +116,10 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
82
116
  rules: { project: ManifestConstants.PROJECT_RULES, base: buildBaseRuleHashes() },
83
117
  // The sources this project reads knowledge from (atlas, git mode); a project without any carries none.
84
118
  ...(config.atlas.sources.length === 0 ? {} : { sources: config.atlas.sources }),
119
+ // The prebuilt index: the keys a published pair is checked with, and the switch; neither set, nothing is written.
120
+ ...atlasBlockOf({ config }),
121
+ // The commands and push targets the guards ask about beyond their own list; neither set, nothing is written.
122
+ ...guardBlockOf({ config }),
85
123
  // The remote-host guard reads its policy here; a project without the key has no guard.
86
124
  ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
87
125
  };
@@ -0,0 +1,48 @@
1
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
+ import { dirname, join } from 'node:path';
3
+ import { ProjectLayout } from '../common/index.ts';
4
+ import { projectTmpOf } from '../hooks/project-tmp.ts';
5
+ import { SyncStatuses } from './common/index.ts';
6
+ import type { ISyncAction } from './common/index.ts';
7
+
8
+ /** Beside the other personal files of the developer, gitignored with them. */
9
+ export const CLAUDE_LAUNCH_FILE = `${ProjectLayout.LOCAL_DIRECTORY}/claude.launch.settings.json`;
10
+
11
+ /**
12
+ * What `claude --settings <this file>` adds to a session: `TMPDIR` and `CLAUDE_CODE_TMPDIR` in the project.
13
+ * Claude Code applies an `env` block given this way (and the variables in the launch environment, and the
14
+ * user settings file), but not the same block in the project's own settings, so this is the route that
15
+ * moves its own task-output files and its MCP servers into the project. Absolute paths: the file belongs
16
+ * to one checkout of one developer.
17
+ */
18
+ export const renderClaudeLaunch = (opts: { root: string }): string => {
19
+ const folder = projectTmpOf({ root: opts.root });
20
+
21
+ return `${JSON.stringify({ env: { TMPDIR: folder, CLAUDE_CODE_TMPDIR: folder } }, null, 2)}\n`;
22
+ };
23
+
24
+ /** The launch file when it is missing or written for another folder; nothing to do when it is current. */
25
+ export const planClaudeLaunch = (opts: { root: string }): ISyncAction[] => {
26
+ const path = join(opts.root, CLAUDE_LAUNCH_FILE);
27
+ const text = renderClaudeLaunch({ root: opts.root });
28
+ const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
29
+
30
+ if (before === text) {
31
+ return [];
32
+ }
33
+
34
+ return [
35
+ {
36
+ path,
37
+ status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
38
+ note:
39
+ before === undefined
40
+ ? 'the Claude Code launch file is missing'
41
+ : 'the Claude Code launch file names another folder',
42
+ apply: () => {
43
+ mkdirSync(dirname(path), { recursive: true });
44
+ writeFileSync(path, text);
45
+ },
46
+ },
47
+ ];
48
+ };
package/src/sync/index.ts CHANGED
@@ -4,6 +4,7 @@ export * from './planner.ts';
4
4
  export * from './prune.ts';
5
5
  export * from './settings.ts';
6
6
  export * from './local-choice.ts';
7
+ export * from './claude-launch.ts';
7
8
  export * from './agent-files.ts';
8
9
  export * from './atlas-block.ts';
9
10
  export * from './exclude.ts';
@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
  import { LOCAL_AGENTS_FILE, renderLocalChoice } from '../agents/index.ts';
4
4
  import { ProjectLayout } from '../common/index.ts';
5
+ import { planClaudeLaunch } from './claude-launch.ts';
5
6
  import { SyncStatuses } from './common/index.ts';
6
7
  import type { ISyncAction } from './common/index.ts';
7
8
 
@@ -71,6 +72,7 @@ export const planLocalWorkspace = (opts: { root: string }): ISyncAction[] => {
71
72
 
72
73
  return [
73
74
  ...planIgnoreLine({ root: opts.root, line: `${ProjectLayout.LOCAL_DIRECTORY}/` }),
75
+ ...planClaudeLaunch({ root: opts.root }),
74
76
  {
75
77
  path: directory,
76
78
  status: missing.length === 0 ? SyncStatuses.UNCHANGED : SyncStatuses.CREATED,