@venizia/vulcan 0.4.9 → 0.4.10-0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -50,7 +50,7 @@ An unknown key is an error; every error names the file and the field.
50
50
 
51
51
  ## What ships (`base/`)
52
52
 
53
- - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (50 rules).
53
+ - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (51 rules).
54
54
  - `slots.json` - rules a project picks a wording for (V-W-01 today).
55
55
  - `skills/` - `knowledge-sync`, `docs-writing`, `docs-update`, `build-a-feature` (project-neutral; a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
56
56
  - `hooks/` - `session-start.ts` (prints the rules digest) `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call) `guard-manifest.ts` (refuses a write to the generated `.agents/vulcan.manifest.json`) `guard-package.ts` (denies a hand-written new `package.json` in a layout folder when a recorded preset has a `vulcan add` command for it, else only warns) and `guard-remote-hosts.ts` (only for a config with `remoteHosts`: asks before a command reaches a host that is not listed; whole-name or `*` match, never substring).
package/base/rules.md CHANGED
@@ -49,6 +49,7 @@ An ID the base drops is never reused.
49
49
  | V-P-10 | **Ask once, with a recommendation.** All open decisions in one numbered round, each with a recommended answer worded so that "yes" accepts it; never ask for a fact you can look up; for a reversible choice state the default in one line and continue, only inside what V-P-02, V-P-03 and V-W-06 already allow; stop for an action they reserve, a plan awaiting approval, a change of shape, or a real fork. | SOFT |
50
50
  | V-P-11 | **Reports: answer first, in the reader's form.** Two lines before any detail; evidence as a table, not prose; a long report goes in a file and the message carries the path. The reader decides the form: the owner gets the project's report shape in their own language, with labels and form of address taken from the `owner` config and their profile, never from fixed words; another agent (a session it started, a cross-session message, a subagent) gets the plain format it asked for and nothing more. | SOFT |
51
51
  | V-P-12 | **Delegate by kind; the brief carries the rules.** Mechanical work (sweeps, greps, renames, gates, counting) goes to a smaller-model subagent; judgment stays with the main agent, which re-checks what comes back. A subagent brief carries the goal, the files, read-only by default, "no git writes", the report shape and a size under 400 words, and the rules digest reaches the subagent (through the tool's subagent-start hook where one exists, otherwise in the brief); the template is `node_modules/@venizia/vulcan/base/references/delegation-brief.md`. | SOFT - the brief; a subagent-start hook where the tool has one |
52
+ | V-P-13 | **Name the flow.** Only in a project that logs events (`events.log` on; without it the command writes a line nobody reads, so skip this rule). When you start work that belongs to a flow (`F-n`), log it once, in the owner's language: `vulcan event add --kind flow --flow F-n --title "<a title the owner reads>" --why "<one line, why it exists>"`; log a new one when the title or the reason changes (the newest wins). A board shows the title as the flow's heading; without one it shows the words of its pull request or its first line, marked as having no title yet. | SOFT |
52
53
 
53
54
  ## B - Build and quality
54
55
 
@@ -337,6 +337,22 @@
337
337
  width: 32px;
338
338
  padding: 0;
339
339
  }
340
+ .btn[aria-pressed='true'] {
341
+ background: var(--soft);
342
+ border-color: var(--ink);
343
+ }
344
+ .untitled {
345
+ color: var(--muted);
346
+ font-size: 12px;
347
+ font-weight: 400;
348
+ margin-left: 8px;
349
+ }
350
+ .dh .why {
351
+ margin: 4px 0 0;
352
+ color: var(--muted);
353
+ font-size: 13px;
354
+ line-height: 1.4;
355
+ }
340
356
 
341
357
  .seg {
342
358
  display: inline-flex;
@@ -2361,7 +2377,7 @@
2361
2377
  <header class="bar">
2362
2378
  <span class="mark" id="mark"></span><span class="brule" aria-hidden="true"></span>
2363
2379
  <h1 id="boardTitle"></h1>
2364
- <div class="tabs" role="tablist" aria-label="Màn hình" data-i18n-aria-label="Màn hình">
2380
+ <div class="tabs" role="tablist" aria-label="Screens" data-i18n-aria-label="Màn hình">
2365
2381
  <button
2366
2382
  class="tab"
2367
2383
  role="tab"
@@ -2370,7 +2386,7 @@
2370
2386
  aria-controls="vFlows"
2371
2387
  type="button"
2372
2388
  >
2373
- <span data-i18n="Luồng">Luồng</span>
2389
+ <span data-i18n="Luồng">Flows</span>
2374
2390
  </button>
2375
2391
  <button
2376
2392
  class="tab"
@@ -2385,25 +2401,28 @@
2385
2401
  </div>
2386
2402
  <span class="spacer"></span>
2387
2403
  <span class="since" id="since"
2388
- ><span id="sinceTxt"><span data-i18n="Đang tải">Đang tải</span></span></span
2404
+ ><span id="sinceTxt"><span data-i18n="Đang tải">Loading</span></span></span
2389
2405
  >
2390
2406
  <button class="btn" type="button" id="bSeen">
2391
- <span data-i18n="Đánh dấu đã xem">Đánh dấu đã xem</span>
2407
+ <span data-i18n="Đánh dấu đã xem">Mark as seen</span>
2392
2408
  </button>
2393
2409
  <span class="fresh" id="fresh"></span>
2410
+ <button class="btn" type="button" id="bPlumb" aria-pressed="false">
2411
+ <span data-i18n="pl.all">Show all events</span>
2412
+ </button>
2394
2413
  <button class="btn lang" type="button" id="bLang"></button>
2395
2414
  <button
2396
2415
  class="btn sq theme"
2397
2416
  type="button"
2398
2417
  id="bTheme"
2399
- aria-label="Giao diện: sáng"
2418
+ aria-label="Theme: light"
2400
2419
  data-i18n-aria-label="Giao diện: sáng"
2401
2420
  ></button>
2402
2421
  <button
2403
2422
  class="btn sq"
2404
2423
  type="button"
2405
2424
  id="bKeys"
2406
- aria-label="Phím tắt"
2425
+ aria-label="Shortcuts"
2407
2426
  data-i18n-aria-label="Phím tắt"
2408
2427
  aria-expanded="false"
2409
2428
  >
@@ -2412,27 +2431,23 @@
2412
2431
  </header>
2413
2432
 
2414
2433
  <main class="view on" id="vFlows" role="tabpanel" aria-labelledby="tFlows">
2415
- <section
2416
- class="pane list"
2417
- aria-label="Danh sách luồng"
2418
- data-i18n-aria-label="Danh sách luồng"
2419
- >
2434
+ <section class="pane list" aria-label="Flow list" data-i18n-aria-label="Danh sách luồng">
2420
2435
  <div class="ph">
2421
- <h2><span data-i18n="Luồng việc">Luồng việc</span></h2>
2436
+ <h2><span data-i18n="Luồng việc">Flows</span></h2>
2422
2437
  <span class="n" id="flowN"></span><span class="spacer"></span>
2423
2438
  <div
2424
2439
  class="seg"
2425
2440
  role="radiogroup"
2426
2441
  id="vmode"
2427
2442
  data-i18n-aria-label="vm.label"
2428
- aria-label="vm.label"
2443
+ aria-label="View"
2429
2444
  >
2430
2445
  <button type="button" role="radio" data-mode="list">
2431
- <span data-i18n="vm.list">vm.list</span></button
2446
+ <span data-i18n="vm.list">List</span></button
2432
2447
  ><button type="button" role="radio" data-mode="diagram">
2433
- <span data-i18n="vm.diagram">vm.diagram</span></button
2448
+ <span data-i18n="vm.diagram">Flow diagram</span></button
2434
2449
  ><button type="button" role="radio" data-mode="board">
2435
- <span data-i18n="vm.board">vm.board</span>
2450
+ <span data-i18n="vm.board">Board</span>
2436
2451
  </button>
2437
2452
  </div>
2438
2453
  </div>
@@ -2440,8 +2455,7 @@
2440
2455
  <p class="empty">
2441
2456
  <span
2442
2457
  data-i18n="Đang tải luồng việc. Luồng nào có sự kiện sẽ hiện ở đây, việc cần anh lên trước."
2443
- >Đang tải luồng việc. Luồng nào có sự kiện sẽ hiện ở đây, việc cần anh lên
2444
- trước.</span
2458
+ >Loading flows. Flows with events show here, the ones that need you first.</span
2445
2459
  >
2446
2460
  </p>
2447
2461
  </div>
@@ -2453,31 +2467,31 @@
2453
2467
  aria-orientation="vertical"
2454
2468
  tabindex="0"
2455
2469
  data-i18n-aria-label="split"
2456
- aria-label="split"
2470
+ aria-label="Resize the flow list and the detail"
2457
2471
  aria-valuemin="25"
2458
2472
  aria-valuemax="75"
2459
2473
  ></div>
2460
2474
  <section
2461
2475
  class="pane detail"
2462
2476
  id="detail"
2463
- aria-label="Chi tiết luồng"
2477
+ aria-label="Flow detail"
2464
2478
  data-i18n-aria-label="Chi tiết luồng"
2465
2479
  data-comment-target
2466
2480
  >
2467
2481
  <div class="pb">
2468
2482
  <div id="dEmpty">
2469
2483
  <div class="dh">
2470
- <h3><span data-i18n="Hôm nay">Hôm nay</span></h3>
2471
- <p class="meta" id="sumLine"><span data-i18n="Đang tải">Đang tải</span></p>
2484
+ <h3><span data-i18n="Hôm nay">Today</span></h3>
2485
+ <p class="meta" id="sumLine"><span data-i18n="Đang tải">Loading</span></p>
2472
2486
  <p class="meta">
2473
2487
  <span
2474
2488
  data-i18n="Chọn một luồng ở bên trái để xem từng bước, từng vòng review và tin nhắn. Phím j, k để chuyển, Enter để mở."
2475
- >Chọn một luồng ở bên trái để xem từng bước, từng vòng review và tin nhắn. Phím
2476
- j, k để chuyển, Enter để mở.</span
2489
+ >Pick a flow on the left to see each stage, each review round and the messages.
2490
+ j and k move, Enter opens.</span
2477
2491
  >
2478
2492
  </p>
2479
2493
  </div>
2480
- <h4 class="dlabel"><span data-i18n="Sự kiện mới nhất">Sự kiện mới nhất</span></h4>
2494
+ <h4 class="dlabel"><span data-i18n="Sự kiện mới nhất">Latest events</span></h4>
2481
2495
  <ul class="evs" id="recent" style="padding: 8px 16px 16px"></ul>
2482
2496
  </div>
2483
2497
  <div id="dBody" hidden></div>
@@ -2488,7 +2502,7 @@
2488
2502
  <main class="view" id="vAgents" role="tabpanel" aria-labelledby="tAgents">
2489
2503
  <section class="pane graphp" aria-label="Agent graph">
2490
2504
  <div class="ph">
2491
- <h2><span data-i18n="gr.title">gr.title</span></h2>
2505
+ <h2><span data-i18n="gr.title">Agent graph</span></h2>
2492
2506
  <span class="n" id="agN"></span><span class="spacer"></span
2493
2507
  ><span class="glegend" id="gLegend"></span>
2494
2508
  </div>
@@ -2498,21 +2512,25 @@
2498
2512
  </section>
2499
2513
  <section class="pane gside" aria-label="Pair">
2500
2514
  <div class="ph">
2501
- <h2 id="gSideT"><span data-i18n="gr.pick">gr.pick</span></h2>
2515
+ <h2 id="gSideT"><span data-i18n="gr.pick">Pick a link</span></h2>
2516
+ </div>
2517
+ <div class="pb" id="gSide">
2518
+ <p class="empty" data-i18n="gr.hint">
2519
+ Click a line between two agents to see what passed between them and the flows it
2520
+ touched. Click an agent for its details.
2521
+ </p>
2502
2522
  </div>
2503
- <div class="pb" id="gSide"><p class="empty" data-i18n="gr.hint">gr.hint</p></div>
2504
2523
  </section>
2505
2524
  </main>
2506
2525
 
2507
2526
  <footer
2508
2527
  class="dock"
2509
2528
  id="dock"
2510
- aria-label="Các agent đang chạy"
2529
+ aria-label="Running agents"
2511
2530
  data-i18n-aria-label="Các agent đang chạy"
2512
2531
  >
2513
2532
  <div class="dock-lbl">
2514
- <b id="dockN">Agent</b
2515
- ><span id="dockSum"><span data-i18n="đang tải">đang tải</span></span>
2533
+ <b id="dockN">Agent</b><span id="dockSum"><span data-i18n="đang tải">loading</span></span>
2516
2534
  </div>
2517
2535
  </footer>
2518
2536
  </div>
@@ -2531,21 +2549,21 @@
2531
2549
  id="keys"
2532
2550
  hidden
2533
2551
  role="dialog"
2534
- aria-label="Phím tắt"
2552
+ aria-label="Shortcuts"
2535
2553
  data-i18n-aria-label="Phím tắt"
2536
2554
  >
2537
- <h2><span data-i18n="Phím tắt">Phím tắt</span></h2>
2555
+ <h2><span data-i18n="Phím tắt">Shortcuts</span></h2>
2538
2556
  <dl>
2539
2557
  <dt>j / k</dt>
2540
- <dd><span data-i18n="Luồng sau / trước">Luồng sau / trước</span></dd>
2558
+ <dd><span data-i18n="Luồng sau / trước">Next / previous flow</span></dd>
2541
2559
  <dt>Enter</dt>
2542
- <dd><span data-i18n="Mở chi tiết">Mở chi tiết</span></dd>
2560
+ <dd><span data-i18n="Mở chi tiết">Open detail</span></dd>
2543
2561
  <dt>e</dt>
2544
- <dd><span data-i18n="Các bước hoặc mọi sự kiện">Các bước hoặc mọi sự kiện</span></dd>
2562
+ <dd><span data-i18n="Các bước hoặc mọi sự kiện">Stages or all events</span></dd>
2545
2563
  <dt>Esc</dt>
2546
- <dd><span data-i18n="Đóng">Đóng</span></dd>
2564
+ <dd><span data-i18n="Đóng">Close</span></dd>
2547
2565
  <dt>?</dt>
2548
- <dd><span data-i18n="Bảng này">Bảng này</span></dd>
2566
+ <dd><span data-i18n="Bảng này">This panel</span></dd>
2549
2567
  </dl>
2550
2568
  </div>
2551
2569
 
@@ -2720,6 +2738,18 @@
2720
2738
  DICT.vi['gr.events'] = 'sự kiện';
2721
2739
  DICT.en['gr.flows'] = 'Flows';
2722
2740
  DICT.vi['gr.flows'] = 'Luồng';
2741
+ DICT.en['pl.all'] = 'Show all events';
2742
+ DICT.vi['pl.all'] = 'Hiện mọi sự kiện';
2743
+ DICT.en['pl.tip'] =
2744
+ 'Sessions starting and stopping, subagents and prompts that only wait are hidden; this shows them';
2745
+ DICT.vi['pl.tip'] =
2746
+ 'Phiên bắt đầu và kết thúc, subagent và lời nhắc chỉ để chờ đang được ẩn; nút này hiện chúng';
2747
+ DICT.en['fl.untitled'] = 'no title yet';
2748
+ DICT.vi['fl.untitled'] = 'chưa có tên';
2749
+ DICT.en['k.flow'] = 'flow title';
2750
+ DICT.vi['k.flow'] = 'tên luồng';
2751
+ DICT.en['k.agent'] = 'agent activity';
2752
+ DICT.vi['k.agent'] = 'hoạt động agent';
2723
2753
  DICT.en['vm.label'] = 'View';
2724
2754
  DICT.vi['vm.label'] = 'Cách xem';
2725
2755
  DICT.en['vm.list'] = 'List';
@@ -2801,6 +2831,8 @@
2801
2831
  release: 'phát hành',
2802
2832
  handoff: 'bàn giao',
2803
2833
  msg: 'tin nhắn',
2834
+ flow: 'k.flow',
2835
+ agent: 'k.agent',
2804
2836
  };
2805
2837
  const LS = LS_PREFIX + 'lastSeen';
2806
2838
  const $ = (id) => document.getElementById(id);
@@ -2822,6 +2854,10 @@
2822
2854
  localStorage.setItem(k, v);
2823
2855
  } catch {}
2824
2856
  };
2857
+ // Agent plumbing (sessions, subagents, the harness waiting) is hidden until the owner asks for all events.
2858
+ const PLUMB_LS = LS_PREFIX + 'plumbing';
2859
+ let showPlumbing = lsGet(PLUMB_LS) === '1';
2860
+ const keepEv = (e) => showPlumbing || !e.plumbing;
2825
2861
  const hhmm = (iso) => {
2826
2862
  const d = new Date(iso);
2827
2863
  return isNaN(d)
@@ -2868,6 +2904,8 @@
2868
2904
  merge: 6,
2869
2905
  release: 7,
2870
2906
  handoff: 8,
2907
+ flow: 0,
2908
+ agent: 0,
2871
2909
  };
2872
2910
  const normEv = (e) =>
2873
2911
  typeof e.stage === 'number'
@@ -2921,7 +2959,8 @@
2921
2959
  function fold() {
2922
2960
  const out = [];
2923
2961
  for (const f of DATA.flows) {
2924
- const evs = f.events.map(normEv).sort(byTs);
2962
+ const evs = f.events.filter(keepEv).map(normEv).sort(byTs);
2963
+ if (!evs.length) continue;
2925
2964
  const last = evs.find((e) => e.id === f.lastId) || evs[evs.length - 1];
2926
2965
  const lastAsk = f.askId ? evs.find((e) => e.id === f.askId) : undefined;
2927
2966
  const att = {};
@@ -2932,7 +2971,12 @@
2932
2971
  const fresh = evs.filter((e) => e.ts > lastSeen);
2933
2972
  out.push({
2934
2973
  id: f.id,
2935
- f: { title: f.title, repo: f.repo },
2974
+ f: {
2975
+ title: f.title,
2976
+ repo: f.repo,
2977
+ why: f.why,
2978
+ named: f.named === true || f.id === 'Unsorted',
2979
+ },
2936
2980
  evs,
2937
2981
  last,
2938
2982
  state: f.state,
@@ -3069,6 +3113,7 @@
3069
3113
  const tt = el('div', 'tt');
3070
3114
  tt.append(el('div', 't', fl.f.title));
3071
3115
  const sub = el('div', 'sub');
3116
+ if (!fl.f.named) sub.append(el('span', 'untitled', t('fl.untitled')));
3072
3117
  sub.append(
3073
3118
  el('span', 'repo', fl.f.repo),
3074
3119
  el(
@@ -3238,7 +3283,10 @@
3238
3283
  el('span', 'repo', fl.f.repo),
3239
3284
  el('span', 'pill ' + fl.state, t(STATE_TXT[fl.state])),
3240
3285
  );
3241
- dh.append(top, el('h3', null, fl.f.title));
3286
+ const heading = el('h3', null, fl.f.title);
3287
+ if (!fl.f.named) heading.append(el('span', 'untitled', t('fl.untitled')));
3288
+ dh.append(top, heading);
3289
+ if (fl.f.why) dh.append(el('p', 'why', fl.f.why));
3242
3290
  const meta = el('div', 'meta');
3243
3291
  const m = (k, v) => {
3244
3292
  const s = el('span');
@@ -3396,7 +3444,9 @@
3396
3444
  el('span', 'spacer'),
3397
3445
  el('span', 'pill ' + fl.state, t(STATE_TXT[fl.state])),
3398
3446
  );
3399
- c.append(top, el('div', 'kt', fl.f.title), ft);
3447
+ const kt = el('div', 'kt', fl.f.title);
3448
+ if (!fl.f.named) kt.append(el('span', 'untitled', t('fl.untitled')));
3449
+ c.append(top, kt, ft);
3400
3450
  c.addEventListener('click', () => select(fl.id, true));
3401
3451
  kl.append(c);
3402
3452
  }
@@ -4505,6 +4555,7 @@
4505
4555
  for (const a of ['aria-label', 'title', 'placeholder'])
4506
4556
  for (const e of document.querySelectorAll('[data-i18n-' + a + ']'))
4507
4557
  e.setAttribute(a, t(e.getAttribute('data-i18n-' + a)));
4558
+ syncPlumb();
4508
4559
  const b = $('bLang');
4509
4560
  b.textContent = lang === 'en' ? 'VI' : 'EN';
4510
4561
  b.setAttribute('aria-label', t('lang.label') + ': ' + t('lang.' + lang));
@@ -4603,6 +4654,12 @@
4603
4654
  if ($('vAgents').classList.contains('on')) renderAgents();
4604
4655
  }).observe($('gWrap'));
4605
4656
  let raf = 0;
4657
+ function loadEvents() {
4658
+ events = DATA.flows
4659
+ .flatMap((f) => f.events)
4660
+ .filter(keepEv)
4661
+ .map(normEv);
4662
+ }
4606
4663
  function schedule() {
4607
4664
  if (raf) return;
4608
4665
  raf = requestAnimationFrame(() => {
@@ -4625,6 +4682,19 @@
4625
4682
  }
4626
4683
  $('tFlows').addEventListener('click', () => showTab('Flows'));
4627
4684
  $('tAgents').addEventListener('click', () => showTab('Agents'));
4685
+ function syncPlumb() {
4686
+ const b = $('bPlumb');
4687
+ b.setAttribute('aria-pressed', String(showPlumbing));
4688
+ b.title = t('pl.tip');
4689
+ }
4690
+ $('bPlumb').addEventListener('click', () => {
4691
+ showPlumbing = !showPlumbing;
4692
+ lsSet(PLUMB_LS, showPlumbing ? '1' : '0');
4693
+ syncPlumb();
4694
+ loadEvents();
4695
+ schedule();
4696
+ });
4697
+ syncPlumb();
4628
4698
  $('bSeen').addEventListener('click', () => {
4629
4699
  lastSeen = new Date().toISOString();
4630
4700
  lsSet(LS, lastSeen);
@@ -4685,7 +4755,7 @@
4685
4755
  img.alt = '';
4686
4756
  $('mark').append(img);
4687
4757
  }
4688
- events = DATA.flows.flatMap((f) => f.events).map(normEv);
4758
+ loadEvents();
4689
4759
  decisions = DATA.decisions;
4690
4760
  agentsDoc = DATA.agents;
4691
4761
  releases = [];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.9",
3
+ "version": "0.4.10-0",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "bugs": {
@@ -44,8 +44,8 @@
44
44
  },
45
45
  "dependencies": {
46
46
  "@clack/prompts": "1.8.1",
47
- "@venizia/vulcan-atlas": "0.4.9",
48
- "@venizia/vulcan-okf": "0.4.9",
47
+ "@venizia/vulcan-atlas": "0.4.10-0",
48
+ "@venizia/vulcan-okf": "0.4.10-0",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
@@ -25,6 +25,10 @@ export class BoardKinds {
25
25
  static readonly RELEASE = 'release';
26
26
  static readonly HANDOFF = 'handoff';
27
27
  static readonly MSG = 'msg';
28
+ /** The line that names a flow: its summary is the title. */
29
+ static readonly FLOW = 'flow';
30
+ /** What the harness does around the work: a session starting or ending, a subagent stopping, a prompt waiting. */
31
+ static readonly AGENT = 'agent';
28
32
  }
29
33
 
30
34
  /** The stages of a flow, in the order of the page's strip. */
@@ -101,6 +105,12 @@ export class BoardConstants {
101
105
  static readonly DATA_MARKER = '<!--BOARD_DATA-->';
102
106
  static readonly GH_TIMEOUT_MS = 15_000;
103
107
  static readonly GH_LIMIT = 30;
108
+ /** A `needs-owner` line whose whole summary is one of these is the harness waiting, not a person asking. */
109
+ static readonly HARNESS_ASKS = new Set<string>([
110
+ 'idle_prompt',
111
+ 'permission_prompt',
112
+ 'elicitation_dialog',
113
+ ]);
104
114
  /** Kinds that mean someone did work on the flow, for the holder. */
105
115
  static readonly WORK_KINDS = [
106
116
  BoardKinds.ASSIGN,
@@ -23,6 +23,12 @@ export interface IBoardEvent {
23
23
  /** What a decision decided: `approve`, `park` or `reject`. */
24
24
  choice?: string;
25
25
  needsOwner?: boolean;
26
+ /** Agent plumbing: kept in the data, hidden by the page until "show all events". It never moves a flow. */
27
+ plumbing?: boolean;
28
+ /** This line names the flow: its summary is the title. */
29
+ isTitle?: boolean;
30
+ /** Only a title line has one: why the flow exists. */
31
+ why?: string;
26
32
  /** Which attempt this is: the nth run of one check, the nth review round. */
27
33
  attempt?: number;
28
34
  /** The check a CI line is about. */
@@ -36,6 +42,10 @@ export interface IBoardEvent {
36
42
  export interface IBoardFlow {
37
43
  id: string;
38
44
  title: string;
45
+ /** The title came from a `flow` line; a flow without one shows its first line and "no title yet". */
46
+ named: boolean;
47
+ /** Why the flow exists, from the newest `flow` line that has one. */
48
+ why?: string;
39
49
  repo?: string;
40
50
  state: TBoardState;
41
51
  /** Who has it now. */
package/src/board/fold.ts CHANGED
@@ -72,19 +72,52 @@ export class BoardFold {
72
72
  const decisions: Record<string, IBoardDecision> = {};
73
73
 
74
74
  for (const [id, lines] of byFlow) {
75
- const events = BoardFold.prepare({ lines });
75
+ // Plumbing (a session, a subagent, the harness waiting) and the lines that name the flow are carried along as
76
+ // lines of the flow; they never move it: not its state, stage, holder or last line. A `flow` line only sets the
77
+ // title and the reason, the newest by time winning.
78
+ const quiet = lines.filter((event) => event.plumbing === true || event.isTitle === true);
79
+ const core = lines.filter((event) => event.plumbing !== true && event.isTitle !== true);
80
+ const named = [...lines].sort(byTime).findLast((event) => event.isTitle === true);
81
+
82
+ if (core.length === 0) {
83
+ flows.push(BoardFold.quietFlow({ id, lines: quiet, named }));
84
+ continue;
85
+ }
86
+
87
+ const events = BoardFold.prepare({ lines: core });
76
88
  const decision = BoardFold.lastDecision({ events });
77
89
 
78
90
  if (decision !== undefined) {
79
91
  decisions[id] = decision;
80
92
  }
81
93
 
82
- flows.push(BoardFold.flowOf({ id, events, owner: opts.owner }));
94
+ const flow = BoardFold.flowOf({ id, events, owner: opts.owner });
95
+
96
+ flows.push({
97
+ ...flow,
98
+ ...BoardFold.headingOf({ named }),
99
+ ...(quiet.length === 0
100
+ ? {}
101
+ : { events: BoardFold.withQuiet({ events: flow.events, quiet }) }),
102
+ });
83
103
  }
84
104
 
85
105
  return { flows, decisions };
86
106
  }
87
107
 
108
+ /**
109
+ * A `needs-owner` line the harness raised: the hook recorded the notification type (so a title such as "Claude
110
+ * needs your permission" is still the harness). A line without the field is judged by its summary alone, the way
111
+ * lines written before the field existed are: the name of a prompt, in any case.
112
+ */
113
+ private static isHarnessAsk(opts: { line: IEvent }): boolean {
114
+ return (
115
+ opts.line.kind === EventKinds.NEEDS_OWNER &&
116
+ (opts.line.notification !== undefined ||
117
+ BoardConstants.HARNESS_ASKS.has(opts.line.summary.trim().toLowerCase()))
118
+ );
119
+ }
120
+
88
121
  private static eventOf(opts: { line: IEvent }): IBoardEvent | undefined {
89
122
  const { line } = opts;
90
123
  const base = {
@@ -132,7 +165,26 @@ export class BoardFold {
132
165
  }
133
166
 
134
167
  case EventKinds.NEEDS_OWNER: {
135
- return { ...base, kind: BoardKinds.NOTE, stage: -1, needsOwner: true };
168
+ // The harness waiting for a prompt is not a person asking: it is shown only on request and never makes a flow wait.
169
+ return BoardFold.isHarnessAsk({ line })
170
+ ? { ...base, kind: BoardKinds.NOTE, stage: -1, plumbing: true }
171
+ : { ...base, kind: BoardKinds.NOTE, stage: -1, needsOwner: true };
172
+ }
173
+
174
+ case EventKinds.FLOW: {
175
+ return {
176
+ ...base,
177
+ kind: BoardKinds.FLOW,
178
+ stage: BoardStages.REQUEST,
179
+ isTitle: true,
180
+ ...(line.why === undefined ? {} : { why: line.why }),
181
+ };
182
+ }
183
+
184
+ case EventKinds.SESSION_START:
185
+ case EventKinds.SESSION_STOP:
186
+ case EventKinds.SUBAGENT_STOP: {
187
+ return { ...base, kind: BoardKinds.AGENT, stage: -1, plumbing: true };
136
188
  }
137
189
 
138
190
  case EventKinds.DECISION: {
@@ -156,7 +208,7 @@ export class BoardFold {
156
208
  const { agents, line } = opts;
157
209
  const known = agents[line.actor];
158
210
 
159
- if (line.kind === EventKinds.SUBAGENT_STOP) {
211
+ if (line.kind === EventKinds.SUBAGENT_STOP || BoardFold.isHarnessAsk({ line })) {
160
212
  return;
161
213
  }
162
214
 
@@ -261,6 +313,7 @@ export class BoardFold {
261
313
  return {
262
314
  id,
263
315
  title: BoardFold.titleOf({ id, events }),
316
+ named: false,
264
317
  ...(repo === undefined ? {} : { repo }),
265
318
  state,
266
319
  holder: BoardFold.holderOf({ events, state, owner: opts.owner }),
@@ -278,6 +331,62 @@ export class BoardFold {
278
331
  };
279
332
  }
280
333
 
334
+ /** The title and reason a `flow` line gives; its reason goes with it, and a newer line without one drops the old reason. */
335
+ private static headingOf(opts: { named: IBoardEvent | undefined }): {
336
+ title?: string;
337
+ named: boolean;
338
+ why?: string;
339
+ } {
340
+ const { named } = opts;
341
+
342
+ return named === undefined
343
+ ? { named: false }
344
+ : {
345
+ title: named.summary,
346
+ named: true,
347
+ ...(named.why === undefined ? {} : { why: named.why }),
348
+ };
349
+ }
350
+
351
+ /**
352
+ * A flow with no line of work: only plumbing and `flow` lines. It is running (a closed group would hide what was just
353
+ * asked for), held by whoever wrote last; plumbing shows only when the page shows all events, a `flow` line always.
354
+ */
355
+ private static quietFlow(opts: {
356
+ id: string;
357
+ lines: IBoardEvent[];
358
+ named: IBoardEvent | undefined;
359
+ }): IBoardFlow {
360
+ const events = [...opts.lines]
361
+ .sort(byTime)
362
+ .map((event) => ({ ...event, stage: BoardStages.REQUEST }));
363
+ const last = events[events.length - 1];
364
+
365
+ return {
366
+ id: opts.id,
367
+ title: opts.id,
368
+ ...BoardFold.headingOf({ named: opts.named }),
369
+ state: BoardStates.RUNNING,
370
+ holder: last.actor,
371
+ stages: [BoardStages.REQUEST],
372
+ cur: BoardStages.REQUEST,
373
+ lastId: last.id,
374
+ ciRuns: 0,
375
+ reviewRounds: 0,
376
+ events,
377
+ };
378
+ }
379
+
380
+ /** The quiet lines among the lines of a flow, each at the stage the flow was at when it happened. */
381
+ private static withQuiet(opts: { events: IBoardEvent[]; quiet: IBoardEvent[] }): IBoardEvent[] {
382
+ const placed = opts.quiet.map((event) => ({
383
+ ...event,
384
+ stage: opts.events.findLast((core) => core.ts <= event.ts)?.stage ?? BoardStages.REQUEST,
385
+ }));
386
+
387
+ return [...opts.events, ...placed].sort(byTime);
388
+ }
389
+
281
390
  private static stateOf(opts: {
282
391
  events: IBoardEvent[];
283
392
  live: IBoardEvent[];
@@ -39,7 +39,7 @@ Usage: bun x vulcan <command>
39
39
  List the workspace packages a change touches (changed ones and what
40
40
  depends on them) with the checks each has; template prints a CI file that
41
41
  runs exactly those; exit 2 on bad input
42
- event add --kind <k> --summary <text> [--flow F-n] [--ref <r>] [--status approve|park|reject] | tail [--since <time>] [--json] [--dir <folder>]
42
+ event add --kind <k> --summary <text> [--flow F-n] [--ref <r>] [--status approve|park|reject] | add --kind flow --flow F-n --title <text> [--why <text>] | tail [--since <time>] [--json] [--dir <folder>]
43
43
  Write a line to the agent event log (.agents/local/events/<day>.jsonl) or
44
44
  read it; with events.log on, sync installs the Claude Code hooks that
45
45
  write it; exit 2 on bad input
@@ -17,6 +17,7 @@ import { EventLog } from './log.ts';
17
17
  import { EventSettings } from './settings.ts';
18
18
 
19
19
  const USAGE = `usage: vulcan event add ${EventFlags.KIND} <kind> ${EventFlags.SUMMARY} <text> [${EventFlags.FLOW} F-n] [${EventFlags.REF} <ref>] [${EventFlags.STATUS} <${[...EventStatuses.SCHEME_SET].join('|')}>] [${EventFlags.ACTOR} <name>] [${EventFlags.DIR} <folder>]
20
+ vulcan event add ${EventFlags.KIND} ${EventKinds.FLOW} ${EventFlags.FLOW} F-n ${EventFlags.TITLE} <text> [${EventFlags.WHY} <text>] [${EventFlags.ACTOR} <name>] [${EventFlags.DIR} <folder>]
20
21
  vulcan event tail [${EventFlags.SINCE} <time>] [${EventFlags.JSON}] [${EventFlags.DIR} <folder>]
21
22
  kinds: ${[...EventKinds.SCHEME_SET].join(', ')}`;
22
23
 
@@ -83,7 +84,9 @@ export class EventCommand {
83
84
  private static add(opts: { cwd: string; values: TFlagValues }): number {
84
85
  const { values } = opts;
85
86
  const kind = values[EventFlags.KIND];
86
- const summary = values[EventFlags.SUMMARY];
87
+ const isFlow = kind === EventKinds.FLOW;
88
+ // A flow line is named by its title: the title is its summary, and `--summary` is not a second way to say it.
89
+ const summary = isFlow ? values[EventFlags.TITLE] : values[EventFlags.SUMMARY];
87
90
  const flow = values[EventFlags.FLOW];
88
91
 
89
92
  if (kind === undefined || !EventKinds.isValid(kind)) {
@@ -95,7 +98,23 @@ export class EventCommand {
95
98
  }
96
99
 
97
100
  if (summary === undefined || summary.trim() === '') {
98
- process.stderr.write(`event: ${EventFlags.SUMMARY} needs a short text\n`);
101
+ process.stderr.write(
102
+ `event: ${isFlow ? EventFlags.TITLE : EventFlags.SUMMARY} needs a short text\n`,
103
+ );
104
+
105
+ return ExitCodes.USAGE;
106
+ }
107
+
108
+ if (
109
+ isFlow
110
+ ? values[EventFlags.SUMMARY] !== undefined
111
+ : values[EventFlags.TITLE] !== undefined || values[EventFlags.WHY] !== undefined
112
+ ) {
113
+ process.stderr.write(
114
+ isFlow
115
+ ? `event: a flow line takes ${EventFlags.TITLE} and ${EventFlags.WHY}, not ${EventFlags.SUMMARY}\n`
116
+ : `event: ${EventFlags.TITLE} and ${EventFlags.WHY} belong to a flow line only\n`,
117
+ );
99
118
 
100
119
  return ExitCodes.USAGE;
101
120
  }
@@ -124,6 +143,12 @@ export class EventCommand {
124
143
  }
125
144
 
126
145
  const flowId = flow ?? EventFlow.fromBranch({ cwd: opts.cwd });
146
+
147
+ if (isFlow && flowId === undefined) {
148
+ process.stderr.write(`event: a flow line needs ${EventFlags.FLOW} F-n\n`);
149
+
150
+ return ExitCodes.USAGE;
151
+ }
127
152
  const actor =
128
153
  values[EventFlags.ACTOR] === undefined
129
154
  ? EventActor.resolve({
@@ -139,6 +164,7 @@ export class EventCommand {
139
164
  ...(flowId === undefined ? {} : { flowId }),
140
165
  ...(values[EventFlags.REF] === undefined ? {} : { ref: values[EventFlags.REF] }),
141
166
  ...(status === undefined ? {} : { status: status as TEventStatus }),
167
+ ...(values[EventFlags.WHY] === undefined ? {} : { why: values[EventFlags.WHY] }),
142
168
  });
143
169
 
144
170
  try {
@@ -10,6 +10,8 @@ export class EventKinds {
10
10
  static readonly PR = 'pr';
11
11
  /** The owner's answer to a flow, written by whoever relays it; its `status` says which. */
12
12
  static readonly DECISION = 'decision';
13
+ /** A flow's title and the one-line reason for it, in the owner's language; the newest per flow wins. */
14
+ static readonly FLOW = 'flow';
13
15
 
14
16
  static readonly SCHEME_SET = new Set<string>([
15
17
  this.SESSION_START,
@@ -21,6 +23,7 @@ export class EventKinds {
21
23
  this.COMMIT,
22
24
  this.PR,
23
25
  this.DECISION,
26
+ this.FLOW,
24
27
  ]);
25
28
 
26
29
  static isValid(value: string): boolean {
@@ -58,6 +61,8 @@ export class EventFlags {
58
61
  static readonly FLOW = '--flow';
59
62
  static readonly REF = '--ref';
60
63
  static readonly STATUS = '--status';
64
+ static readonly TITLE = '--title';
65
+ static readonly WHY = '--why';
61
66
  static readonly ACTOR = '--actor';
62
67
  static readonly DIR = '--dir';
63
68
  static readonly SINCE = '--since';
@@ -16,6 +16,10 @@ export interface IEvent {
16
16
  /** Only a `decision` has one. */
17
17
  status?: TEventStatus;
18
18
  ref?: string;
19
+ /** Only a `flow` has one: the one-line reason the flow exists. */
20
+ why?: string;
21
+ /** Only a `needs-owner` the Claude Code hook wrote has one: the notification type that raised it. */
22
+ notification?: string;
19
23
  source: string;
20
24
  }
21
25
 
@@ -42,6 +46,8 @@ export interface IHookEvent {
42
46
  kind: TEventKind;
43
47
  summary: string;
44
48
  ref?: string;
49
+ /** The notification type of a `needs-owner` line. */
50
+ notification?: string;
45
51
  /** Text a flow id may be read from: the first line of a message. */
46
52
  flowText?: string;
47
53
  }
@@ -55,7 +55,11 @@ export class EventHook {
55
55
  const type = text({ value: input.notification_type });
56
56
 
57
57
  return ClaudeHookEvents.OWNER_NOTIFICATIONS.has(type)
58
- ? { kind: EventKinds.NEEDS_OWNER, summary: text({ value: input.title }) || type }
58
+ ? {
59
+ kind: EventKinds.NEEDS_OWNER,
60
+ summary: text({ value: input.title }) || type,
61
+ notification: type,
62
+ }
59
63
  : undefined;
60
64
  }
61
65
 
@@ -153,6 +157,7 @@ export class EventHook {
153
157
  source: EventSources.CLAUDE_HOOK,
154
158
  ...(flowId === undefined ? {} : { flowId }),
155
159
  ...(mapped.ref === undefined ? {} : { ref: mapped.ref }),
160
+ ...(mapped.notification === undefined ? {} : { notification: mapped.notification }),
156
161
  ...(opts.now === undefined ? {} : { now: opts.now }),
157
162
  });
158
163
 
package/src/events/log.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { RecordValue } from '../common/record.ts';
4
- import { EventConstants, EventKinds, EventStatuses } from './common/index.ts';
4
+ import { ClaudeHookEvents, EventConstants, EventKinds, EventStatuses } from './common/index.ts';
5
5
  import type { IEvent, IEventRead, TEventKind, TEventStatus } from './common/index.ts';
6
6
  import { EventText } from './text.ts';
7
7
 
@@ -39,6 +39,8 @@ export class EventLog {
39
39
  flowId?: string;
40
40
  ref?: string;
41
41
  status?: TEventStatus;
42
+ why?: string;
43
+ notification?: string;
42
44
  now?: number;
43
45
  }): IEvent {
44
46
  const now = opts.now ?? Date.now();
@@ -46,6 +48,10 @@ export class EventLog {
46
48
  opts.ref === undefined
47
49
  ? ''
48
50
  : EventText.oneLine({ text: opts.ref, max: EventConstants.REF_MAX });
51
+ const why =
52
+ opts.why === undefined
53
+ ? ''
54
+ : EventText.oneLine({ text: opts.why, max: EventConstants.SUMMARY_MAX });
49
55
 
50
56
  return {
51
57
  id: EventLog.newId({ now }),
@@ -56,6 +62,11 @@ export class EventLog {
56
62
  summary: EventText.oneLine({ text: opts.summary, max: EventConstants.SUMMARY_MAX }),
57
63
  ...(opts.status === undefined ? {} : { status: opts.status }),
58
64
  ...(ref === '' ? {} : { ref }),
65
+ ...(why === '' ? {} : { why }),
66
+ ...(opts.notification !== undefined &&
67
+ ClaudeHookEvents.OWNER_NOTIFICATIONS.has(opts.notification)
68
+ ? { notification: opts.notification }
69
+ : {}),
59
70
  source: opts.source,
60
71
  };
61
72
  }
@@ -130,7 +141,7 @@ export class EventLog {
130
141
  return undefined;
131
142
  }
132
143
 
133
- const { id, ts, flowId, actor, kind, summary, status, ref, source } = value;
144
+ const { id, ts, flowId, actor, kind, summary, status, ref, why, notification, source } = value;
134
145
 
135
146
  if (
136
147
  typeof id !== 'string' ||
@@ -143,7 +154,9 @@ export class EventLog {
143
154
  typeof source !== 'string' ||
144
155
  (flowId !== undefined && typeof flowId !== 'string') ||
145
156
  (status !== undefined && (typeof status !== 'string' || !EventStatuses.isValid(status))) ||
146
- (ref !== undefined && typeof ref !== 'string')
157
+ (ref !== undefined && typeof ref !== 'string') ||
158
+ (why !== undefined && typeof why !== 'string') ||
159
+ (notification !== undefined && typeof notification !== 'string')
147
160
  ) {
148
161
  return undefined;
149
162
  }
@@ -160,6 +173,11 @@ export class EventLog {
160
173
  summary: clean(summary),
161
174
  ...(status === undefined ? {} : { status: status as TEventStatus }),
162
175
  ...(ref === undefined ? {} : { ref: clean(ref) }),
176
+ ...(why === undefined ? {} : { why: clean(why) }),
177
+ // A value that is not one of the types the hook knows is dropped: it is a short enum, not free text.
178
+ ...(notification === undefined || !ClaudeHookEvents.OWNER_NOTIFICATIONS.has(notification)
179
+ ? {}
180
+ : { notification }),
163
181
  source: clean(source),
164
182
  };
165
183
  }
package/src/router.ts CHANGED
@@ -106,6 +106,8 @@ const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
106
106
  EventFlags.FLOW,
107
107
  EventFlags.REF,
108
108
  EventFlags.STATUS,
109
+ EventFlags.TITLE,
110
+ EventFlags.WHY,
109
111
  EventFlags.ACTOR,
110
112
  EventFlags.DIR,
111
113
  EventFlags.SINCE,