@jjanczur/tyran 0.1.10 → 0.1.12
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/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +48 -0
- package/README.md +5 -3
- package/agents/implementer.md +23 -6
- package/agents/retro.md +4 -0
- package/agents/reviewer.md +4 -0
- package/agents/scout.md +4 -1
- package/bin/tyran.mjs +4 -0
- package/hooks/hooks.json +10 -0
- package/hooks/scripts/board-refresh.mjs +89 -0
- package/package.json +1 -1
- package/scripts/board-html.mjs +227 -0
- package/scripts/board.mjs +352 -0
- package/scripts/doctor.mjs +83 -2
- package/scripts/journal.mjs +73 -2
- package/scripts/project.mjs +435 -28
- package/skills/run/SKILL.md +30 -3
- package/skills/status/SKILL.md +5 -1
package/scripts/project.mjs
CHANGED
|
@@ -29,18 +29,25 @@ import {
|
|
|
29
29
|
import { dirname, join, resolve } from 'node:path';
|
|
30
30
|
import { fileURLToPath } from 'node:url';
|
|
31
31
|
import { readJournal, pairSpawns } from './journal.mjs';
|
|
32
|
-
import { escapeInvisible } from './invisible.mjs';
|
|
32
|
+
import { escapeInvisible, jsonEscapeInvisible } from './invisible.mjs';
|
|
33
33
|
|
|
34
34
|
/** Projection file names. Both are fully generated — never hand-edited. */
|
|
35
35
|
export const STATE_FILE = 'STATE.md';
|
|
36
36
|
export const PROGRESS_FILE = 'PROGRESS.md';
|
|
37
|
+
export const BOARD_FILE = 'BOARD.md';
|
|
38
|
+
export const BOARD_JSON_FILE = 'board.json';
|
|
37
39
|
|
|
38
40
|
const GENERATED_HEADER =
|
|
39
41
|
'<!-- GENERATED by tyran scripts/project.mjs - DO NOT EDIT. Source of truth: journal.jsonl -->\n' +
|
|
40
42
|
'<!-- Regenerate: node scripts/project.mjs <journal.jsonl> --out-dir <dir> -->\n';
|
|
41
43
|
|
|
42
44
|
/** Gate results that count as closed. Anything else keeps the gate OPEN. */
|
|
43
|
-
const GATE_PASS = new Set(['pass', 'passed', 'ok', 'green', 'approved', 'closed']);
|
|
45
|
+
const GATE_PASS = new Set(['pass', 'passed', 'ok', 'green', 'approved', 'closed', 'answered']);
|
|
46
|
+
|
|
47
|
+
/** A gate result that means "a human owes an answer" — the board's queue. */
|
|
48
|
+
export const WAITING_RE = /^waiting[_-]?on[_-]?(operator|owner|human)$/i;
|
|
49
|
+
/** A gate kind that means "paused on the subscription window" (overnight mode). */
|
|
50
|
+
export const PAUSED_RE = /usage[-_]?limit/i;
|
|
44
51
|
|
|
45
52
|
/** Longest inline value rendered in a cell or list item, in codepoints. */
|
|
46
53
|
const MAX_CELL = 160;
|
|
@@ -178,6 +185,37 @@ function list(items) {
|
|
|
178
185
|
|
|
179
186
|
// ------------------------------------------------------------------ fold
|
|
180
187
|
|
|
188
|
+
/** The open blockage this agent reported clears when the agent moves on. */
|
|
189
|
+
function clearBlockageBy(state, agent) {
|
|
190
|
+
state.blockages.delete(String(agent));
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** A `review`/`merge` settles the ticket for EVERY agent blocked on it. */
|
|
194
|
+
function clearBlockagesOn(state, ticketId) {
|
|
195
|
+
for (const [key, blockage] of state.blockages) {
|
|
196
|
+
// A ticketless blockage is keyed to its agent and belongs to no ticket —
|
|
197
|
+
// the `(no ticket)` pseudo-ticket of a review/merge without `data.ticket`
|
|
198
|
+
// is a different thing and must not sweep it up.
|
|
199
|
+
if (blockage.ticket != null && String(blockage.ticket) === ticketId) state.blockages.delete(key);
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* A `report` — and a `review`, which is the reviewer's completion event —
|
|
205
|
+
* ENDS that agent's stint, so everything still keyed by its name goes with it.
|
|
206
|
+
*
|
|
207
|
+
* ADR-18 permits a later `spawn` to reuse the name once the prior one is
|
|
208
|
+
* closed, and that is the standard close-spawn recovery path, not an exotic
|
|
209
|
+
* journal. Kept, these records render against the NEXT incarnation: a fresh
|
|
210
|
+
* agent that has emitted nothing showed as `blocked at <old ts>` while
|
|
211
|
+
* `## Open blockages` said _none_ — one document contradicting itself. Cleared
|
|
212
|
+
* here, at fold time, so no reader has to compare timestamps of its own.
|
|
213
|
+
*/
|
|
214
|
+
function closeAgent(state, agent) {
|
|
215
|
+
clearBlockageBy(state, agent);
|
|
216
|
+
state.progressByAgent.delete(String(agent));
|
|
217
|
+
}
|
|
218
|
+
|
|
181
219
|
/**
|
|
182
220
|
* Fold a journal read into the projection state. Pure: no clock, no I/O.
|
|
183
221
|
* Every closed-set event type must hit a branch here; anything else is
|
|
@@ -210,6 +248,26 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
210
248
|
milestones: [],
|
|
211
249
|
unusableAgentNames: [],
|
|
212
250
|
ambiguousAgents: [],
|
|
251
|
+
// agent name -> latest self-reported signal (last one wins)
|
|
252
|
+
progressByAgent: new Map(),
|
|
253
|
+
// agent name -> that agent's open blockage, the ticket inside the value.
|
|
254
|
+
//
|
|
255
|
+
// Keyed by AGENT and not by ticket, because one agent has at most one live
|
|
256
|
+
// blockage (last-blocked-wins, exactly like its last signal) while one
|
|
257
|
+
// ticket can block SEVERAL agents. Under ticket keys the second agent's
|
|
258
|
+
// record replaced the first's, and the second agent's next movement signal
|
|
259
|
+
// then deleted a blockage its owner had never cleared — so an agent stayed
|
|
260
|
+
// stuck with nothing anywhere saying so. The ticket survives as rendered
|
|
261
|
+
// context and as what `review`/`merge` match against.
|
|
262
|
+
//
|
|
263
|
+
// Cleared by `unblocked`/`started`/`working` from the SAME agent, by that
|
|
264
|
+
// agent's report/review, and by a `review`/`merge` on the ticket — AT FOLD
|
|
265
|
+
// TIME, so no reader needs temporal reasoning of its own.
|
|
266
|
+
blockages: new Map(),
|
|
267
|
+
findings: [],
|
|
268
|
+
// `ticket.status` events naming a ticket no other event mentions
|
|
269
|
+
unknownOverrides: [],
|
|
270
|
+
unknownErrorTickets: [],
|
|
213
271
|
};
|
|
214
272
|
|
|
215
273
|
/**
|
|
@@ -259,6 +317,8 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
259
317
|
report: null,
|
|
260
318
|
review: null,
|
|
261
319
|
merge: null,
|
|
320
|
+
override: null,
|
|
321
|
+
error: null,
|
|
262
322
|
lastTs: seenTs ?? null,
|
|
263
323
|
});
|
|
264
324
|
}
|
|
@@ -357,8 +417,60 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
357
417
|
});
|
|
358
418
|
}
|
|
359
419
|
if (data.ticket != null) {
|
|
360
|
-
ticketOf(data.ticket, ts)
|
|
420
|
+
const t = ticketOf(data.ticket, ts);
|
|
421
|
+
t.report = { verdict: data.verdict ?? null, ts, by: data.agent ?? actor };
|
|
422
|
+
t.override = null; // a lifecycle event outranks a hand-set lane
|
|
423
|
+
t.error = null;
|
|
424
|
+
}
|
|
425
|
+
if (data.agent != null) closeAgent(state, data.agent);
|
|
426
|
+
break;
|
|
427
|
+
}
|
|
428
|
+
case 'progress': {
|
|
429
|
+
const agent = String(data.agent ?? '(no agent)');
|
|
430
|
+
state.progressByAgent.set(agent, {
|
|
431
|
+
state: data.state ?? null,
|
|
432
|
+
ticket: data.ticket ?? null,
|
|
433
|
+
detail: data.detail ?? null,
|
|
434
|
+
next: data.next ?? null,
|
|
435
|
+
ts,
|
|
436
|
+
});
|
|
437
|
+
if (data.state === 'blocked') {
|
|
438
|
+
state.blockages.set(agent, { ticket: data.ticket ?? null, agent, detail: data.detail ?? null, ts });
|
|
439
|
+
} else {
|
|
440
|
+
// started / working / unblocked all say "this agent is moving";
|
|
441
|
+
// whatever it reported itself blocked on is no longer blocking.
|
|
442
|
+
clearBlockageBy(state, agent);
|
|
443
|
+
}
|
|
444
|
+
break;
|
|
445
|
+
}
|
|
446
|
+
case 'finding':
|
|
447
|
+
state.findings.push({
|
|
448
|
+
id: data.id ?? null,
|
|
449
|
+
area: data.area ?? null,
|
|
450
|
+
claim: data.claim ?? null,
|
|
451
|
+
proof: data.proof ?? null,
|
|
452
|
+
ticket: data.ticket ?? null,
|
|
453
|
+
confidence: data.confidence ?? null,
|
|
454
|
+
ts,
|
|
455
|
+
actor,
|
|
456
|
+
});
|
|
457
|
+
break;
|
|
458
|
+
case 'ticket.status': {
|
|
459
|
+
// An override is a LANE, not progress: it must never move the percent.
|
|
460
|
+
// Minting a ledger ticket for an id no other event mentions did exactly
|
|
461
|
+
// that — one mistyped id (`T-1O` for `T-10`) enlarged the denominator
|
|
462
|
+
// and dropped the headline percent, while the ticket the operator meant
|
|
463
|
+
// to park stayed unparked. So the override lands only on a ticket the
|
|
464
|
+
// journal already knows; an unknown one is refused OUT LOUD (see
|
|
465
|
+
// `warnings()`) rather than inventing the ticket it names, because a
|
|
466
|
+
// silent exclusion is the failure ADR-19 correction 1 forbids.
|
|
467
|
+
const key = String(data.ticket ?? '(no ticket)');
|
|
468
|
+
if (!state.tickets.has(key)) {
|
|
469
|
+
state.unknownOverrides.push({ ticket: key, ts });
|
|
470
|
+
break;
|
|
361
471
|
}
|
|
472
|
+
const t = ticketOf(key, ts);
|
|
473
|
+
t.override = { column: data.column ?? null, reason: data.reason ?? null, until: data.until ?? null, ts };
|
|
362
474
|
break;
|
|
363
475
|
}
|
|
364
476
|
case 'gate': {
|
|
@@ -369,6 +481,13 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
369
481
|
result: data.result ?? null,
|
|
370
482
|
ts,
|
|
371
483
|
evidence: data.evidence_ref ?? data.evidence ?? null,
|
|
484
|
+
// extra data keys are legal on append; the ask fields ride along so
|
|
485
|
+
// the board's waiting-operator queue can render the question with
|
|
486
|
+
// its recommendation and default (absent on ordinary gates).
|
|
487
|
+
ticket: data.ticket ?? null,
|
|
488
|
+
question: data.question ?? null,
|
|
489
|
+
recommendation: data.recommendation ?? null,
|
|
490
|
+
default: data.default ?? null,
|
|
372
491
|
count: (prev?.count ?? 0) + 1,
|
|
373
492
|
});
|
|
374
493
|
break;
|
|
@@ -376,20 +495,28 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
376
495
|
// `review`/`merge` require data.ticket, but a hand-written or older
|
|
377
496
|
// journal may omit it — bucket those under a visible pseudo-ticket
|
|
378
497
|
// instead of dropping the event (silent loss is the worse failure).
|
|
379
|
-
case 'review':
|
|
380
|
-
ticketOf(data.ticket ?? '(no ticket)', ts)
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
498
|
+
case 'review': {
|
|
499
|
+
const t = ticketOf(data.ticket ?? '(no ticket)', ts);
|
|
500
|
+
t.review = { verdict: data.verdict ?? null, by: data.by ?? actor, ts };
|
|
501
|
+
t.override = null;
|
|
502
|
+
t.error = null;
|
|
503
|
+
clearBlockagesOn(state, t.id);
|
|
504
|
+
// The review is the REVIEWER's completion event, as a report is the
|
|
505
|
+
// implementer's: pairSpawns closes the reviewer's spawn on `data.by`,
|
|
506
|
+
// and the same correlator closes what that spawn left behind. Without
|
|
507
|
+
// it a reviewer's ticketless blockage outlived its own review with no
|
|
508
|
+
// later event that could ever clear it.
|
|
509
|
+
if (data.by != null) closeAgent(state, data.by);
|
|
385
510
|
break;
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
511
|
+
}
|
|
512
|
+
case 'merge': {
|
|
513
|
+
const t = ticketOf(data.ticket ?? '(no ticket)', ts);
|
|
514
|
+
t.merge = { sha: data.sha ?? null, mode: data.mode ?? null, ts };
|
|
515
|
+
t.override = null;
|
|
516
|
+
t.error = null;
|
|
517
|
+
clearBlockagesOn(state, t.id);
|
|
392
518
|
break;
|
|
519
|
+
}
|
|
393
520
|
case 'decision':
|
|
394
521
|
state.decisions.push({ id: data.id ?? '(no id)', text: data.text ?? null, ts, actor });
|
|
395
522
|
break;
|
|
@@ -412,9 +539,25 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
412
539
|
case 'retro.entry':
|
|
413
540
|
state.retro.push({ kind: data.kind ?? null, target: data.target ?? null, confidence: data.confidence ?? null, ts });
|
|
414
541
|
break;
|
|
415
|
-
case 'error':
|
|
542
|
+
case 'error': {
|
|
416
543
|
state.errors.push({ class: data.class ?? null, detail: data.detail ?? null, ts, actor });
|
|
544
|
+
// `data.ticket` is optional metadata on an error, so a typo here is a
|
|
545
|
+
// typo nothing rejected at append. Binding it to a ticket the journal
|
|
546
|
+
// has never seen would MINT that ticket, and a minted ticket is one
|
|
547
|
+
// the denominator counts and no `merge` can ever close — the headline
|
|
548
|
+
// percent falls and never recovers. Same rule as `ticket.status`
|
|
549
|
+
// above, for the same reason; the error itself is still rendered in
|
|
550
|
+
// the Errors table either way, so nothing is lost by not binding it.
|
|
551
|
+
if (data.ticket != null) {
|
|
552
|
+
const key = String(data.ticket);
|
|
553
|
+
if (state.tickets.has(key)) {
|
|
554
|
+
ticketOf(key, ts).error = { class: data.class ?? null, detail: data.detail ?? null, ts };
|
|
555
|
+
} else {
|
|
556
|
+
state.unknownErrorTickets.push({ ticket: key, ts });
|
|
557
|
+
}
|
|
558
|
+
}
|
|
417
559
|
break;
|
|
560
|
+
}
|
|
418
561
|
default:
|
|
419
562
|
state.unknownTypes.set(ev, (state.unknownTypes.get(ev) ?? 0) + 1);
|
|
420
563
|
}
|
|
@@ -433,6 +576,10 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
433
576
|
|
|
434
577
|
/** Human-readable status of one ticket, derived from the strongest signal. */
|
|
435
578
|
export function ticketStatus(t) {
|
|
579
|
+
// A hand-set lane outranks derivation — but only until the next stronger
|
|
580
|
+
// lifecycle event, which clears it AT FOLD TIME. It never touches the
|
|
581
|
+
// merged count or the percent: an override is a lane, not progress.
|
|
582
|
+
if (t.override) return `${t.override.column ?? '(no column)'} (set by ticket.status)`;
|
|
436
583
|
if (t.merge) return `merged (${t.merge.sha ?? 'no sha'})`;
|
|
437
584
|
if (t.review) return `review: ${t.review.verdict ?? 'no verdict'}`;
|
|
438
585
|
if (t.report) return `reported: ${t.report.verdict ?? 'no verdict'}`;
|
|
@@ -440,6 +587,215 @@ export function ticketStatus(t) {
|
|
|
440
587
|
return 'open';
|
|
441
588
|
}
|
|
442
589
|
|
|
590
|
+
// ------------------------------------------------------------------ board
|
|
591
|
+
|
|
592
|
+
/** Lane order, strongest verdicts first. The board renders one section per
|
|
593
|
+
* lane; a ticket lands in exactly ONE, by the precedence in `boardOf`. */
|
|
594
|
+
export const LANES = Object.freeze([
|
|
595
|
+
'waiting-operator',
|
|
596
|
+
'paused-limit',
|
|
597
|
+
'blocked',
|
|
598
|
+
'changes-requested',
|
|
599
|
+
'in-review',
|
|
600
|
+
'in-progress',
|
|
601
|
+
'ready',
|
|
602
|
+
'backlog',
|
|
603
|
+
'parked',
|
|
604
|
+
'done',
|
|
605
|
+
]);
|
|
606
|
+
|
|
607
|
+
const APPROVING_RE = /^approv|^lgtm$|^pass/i;
|
|
608
|
+
|
|
609
|
+
/**
|
|
610
|
+
* The kanban view of a folded state. PURE and clock-free: every timestamp is
|
|
611
|
+
* copied from an event; "how old" is a question only the HTML viewer answers,
|
|
612
|
+
* client-side. A ticket is in exactly one lane, decided strongest-first:
|
|
613
|
+
*
|
|
614
|
+
* done (merge) > parked/waiting-operator/blocked (override) > blocked
|
|
615
|
+
* (open blockage or error) > paused-limit (an open usage-limit gate AND the
|
|
616
|
+
* ticket would otherwise be in progress) > changes-requested > in-review >
|
|
617
|
+
* in-progress > ready (all deps merged; an UNKNOWN dep counts unmet — a
|
|
618
|
+
* typo must refuse to schedule, not schedule) > backlog.
|
|
619
|
+
*/
|
|
620
|
+
export function boardOf(state) {
|
|
621
|
+
const lanes = new Map(LANES.map((lane) => [lane, []]));
|
|
622
|
+
const runningByTicket = new Map();
|
|
623
|
+
for (const a of state.agents) {
|
|
624
|
+
if (a.status === 'running' && a.ticket != null) {
|
|
625
|
+
runningByTicket.set(String(a.ticket), [...(runningByTicket.get(String(a.ticket)) ?? []), a.agent]);
|
|
626
|
+
}
|
|
627
|
+
}
|
|
628
|
+
const mergedIds = new Set(state.ticketList.filter((t) => t.merge !== null).map((t) => t.id));
|
|
629
|
+
const knownIds = new Set(state.ticketList.map((t) => t.id));
|
|
630
|
+
const pausedGate = [...state.gates.values()].find(
|
|
631
|
+
(g) => PAUSED_RE.test(g.kind) && !GATE_PASS.has(String(g.result ?? '').toLowerCase()),
|
|
632
|
+
) ?? null;
|
|
633
|
+
|
|
634
|
+
const asks = [];
|
|
635
|
+
for (const g of state.openGates) {
|
|
636
|
+
if (WAITING_RE.test(String(g.result ?? ''))) {
|
|
637
|
+
asks.push({
|
|
638
|
+
kind: g.kind,
|
|
639
|
+
ticket: g.ticket ?? null,
|
|
640
|
+
question: g.question ?? null,
|
|
641
|
+
recommendation: g.recommendation ?? null,
|
|
642
|
+
default: g.default ?? null,
|
|
643
|
+
since: g.ts ?? null,
|
|
644
|
+
});
|
|
645
|
+
}
|
|
646
|
+
}
|
|
647
|
+
const askTickets = new Set(asks.filter((a) => a.ticket != null).map((a) => String(a.ticket)));
|
|
648
|
+
// Blockages are keyed by AGENT (one ticket can block several agents), so a
|
|
649
|
+
// ticket's blockage is found by scanning for its id, never by lookup.
|
|
650
|
+
const blockageOn = (ticketId) => {
|
|
651
|
+
for (const b of state.blockages.values()) if (b.ticket != null && String(b.ticket) === ticketId) return b;
|
|
652
|
+
return null;
|
|
653
|
+
};
|
|
654
|
+
|
|
655
|
+
for (const t of state.ticketList) {
|
|
656
|
+
const laneOf = () => {
|
|
657
|
+
if (t.merge) return 'done';
|
|
658
|
+
if (t.override?.column && LANES.includes(t.override.column)) return t.override.column;
|
|
659
|
+
if (askTickets.has(t.id)) return 'waiting-operator';
|
|
660
|
+
if (blockageOn(t.id) !== null || t.error !== null) return 'blocked';
|
|
661
|
+
const running = runningByTicket.get(t.id) ?? [];
|
|
662
|
+
if (pausedGate !== null && running.length > 0) return 'paused-limit';
|
|
663
|
+
if (t.review && !APPROVING_RE.test(String(t.review.verdict ?? ''))) return 'changes-requested';
|
|
664
|
+
if (t.review || t.report) return 'in-review';
|
|
665
|
+
if (running.length > 0) return 'in-progress';
|
|
666
|
+
const deps = Array.isArray(t.deps) ? t.deps.map(String) : [];
|
|
667
|
+
const unmet = deps.filter((d) => !mergedIds.has(d));
|
|
668
|
+
const unknown = deps.filter((d) => !knownIds.has(d));
|
|
669
|
+
if (deps.length === 0 || (unmet.length === 0 && unknown.length === 0)) return 'ready';
|
|
670
|
+
return 'backlog';
|
|
671
|
+
};
|
|
672
|
+
const lane = laneOf();
|
|
673
|
+
const deps = Array.isArray(t.deps) ? t.deps.map(String) : [];
|
|
674
|
+
const annotations = [];
|
|
675
|
+
if (lane === 'in-review' && t.review && APPROVING_RE.test(String(t.review.verdict ?? ''))) {
|
|
676
|
+
annotations.push('approved, awaiting merge');
|
|
677
|
+
}
|
|
678
|
+
if (lane === 'blocked') {
|
|
679
|
+
const b = blockageOn(t.id);
|
|
680
|
+
if (b) annotations.push(b.detail ?? 'blocked');
|
|
681
|
+
else if (t.error) annotations.push(`error: ${t.error.class ?? 'unknown'}`);
|
|
682
|
+
}
|
|
683
|
+
if (t.override) annotations.push(t.override.reason ?? 'set by ticket.status');
|
|
684
|
+
if (lane === 'backlog') {
|
|
685
|
+
for (const d of deps.filter((x) => !knownIds.has(x))) annotations.push(`dep ${d} (unknown)`);
|
|
686
|
+
}
|
|
687
|
+
lanes.get(lane).push({
|
|
688
|
+
id: t.id,
|
|
689
|
+
title: t.title,
|
|
690
|
+
agents: runningByTicket.get(t.id) ?? [],
|
|
691
|
+
since: t.lastTs,
|
|
692
|
+
annotation: annotations.length > 0 ? annotations.join(' · ') : null,
|
|
693
|
+
});
|
|
694
|
+
}
|
|
695
|
+
|
|
696
|
+
const agents = state.agents
|
|
697
|
+
.filter((a) => a.status === 'running')
|
|
698
|
+
.map((a) => {
|
|
699
|
+
const signal = state.progressByAgent.get(a.agent) ?? null;
|
|
700
|
+
return {
|
|
701
|
+
agent: a.agent,
|
|
702
|
+
role: a.role,
|
|
703
|
+
ticket: a.ticket,
|
|
704
|
+
state: signal?.state ?? 'running',
|
|
705
|
+
detail: signal?.detail ?? null,
|
|
706
|
+
next: signal?.next ?? null,
|
|
707
|
+
last_signal: signal?.ts ?? a.spawnTs,
|
|
708
|
+
};
|
|
709
|
+
});
|
|
710
|
+
|
|
711
|
+
return {
|
|
712
|
+
lanes,
|
|
713
|
+
asks,
|
|
714
|
+
agents,
|
|
715
|
+
paused: pausedGate === null
|
|
716
|
+
? null
|
|
717
|
+
: { kind: pausedGate.kind, result: pausedGate.result, since: pausedGate.ts ?? null },
|
|
718
|
+
};
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
/** BOARD.md — the waiting queue first, then the agent strip, then the lanes. */
|
|
722
|
+
export function renderBoard(state, board = boardOf(state)) {
|
|
723
|
+
const parts = [GENERATED_HEADER, `# BOARD — ${inline(state.initiatives)}\n\n`];
|
|
724
|
+
parts.push(`**Progress:** ${progressLine(state)}\n`);
|
|
725
|
+
if (board.paused !== null) {
|
|
726
|
+
parts.push(`\n**PAUSED** on gate ${inline(board.paused.kind)} (${inline(board.paused.result)}) since ${inline(board.paused.since)}\n`);
|
|
727
|
+
}
|
|
728
|
+
|
|
729
|
+
parts.push('\n## Waiting on operator\n\n');
|
|
730
|
+
parts.push(
|
|
731
|
+
table(
|
|
732
|
+
['Question', 'Recommendation', 'Default', 'Ticket', 'Gate', 'Since'],
|
|
733
|
+
board.asks.map((a) => [
|
|
734
|
+
inline(a.question ?? '(no question recorded)'),
|
|
735
|
+
inline(a.recommendation),
|
|
736
|
+
inline(a.default),
|
|
737
|
+
inline(a.ticket),
|
|
738
|
+
inline(a.kind),
|
|
739
|
+
inline(a.since),
|
|
740
|
+
]),
|
|
741
|
+
),
|
|
742
|
+
);
|
|
743
|
+
|
|
744
|
+
parts.push('\n## Agents\n\n');
|
|
745
|
+
parts.push(
|
|
746
|
+
table(
|
|
747
|
+
['Agent', 'Role', 'Ticket', 'State', 'Detail', 'Last signal'],
|
|
748
|
+
sortByKey(board.agents, (a) => a.agent).map((a) => [
|
|
749
|
+
inline(a.agent),
|
|
750
|
+
inline(a.role),
|
|
751
|
+
inline(a.ticket),
|
|
752
|
+
inline(a.state),
|
|
753
|
+
inline(a.detail),
|
|
754
|
+
inline(a.last_signal),
|
|
755
|
+
]),
|
|
756
|
+
),
|
|
757
|
+
);
|
|
758
|
+
|
|
759
|
+
for (const lane of LANES) {
|
|
760
|
+
const cards = board.lanes.get(lane);
|
|
761
|
+
parts.push(`\n## ${lane} (${cards.length})\n\n`);
|
|
762
|
+
parts.push(
|
|
763
|
+
list(
|
|
764
|
+
cards.map(
|
|
765
|
+
(c) =>
|
|
766
|
+
`\`${inline(c.id)}\`${c.title ? ` — ${inline(c.title)}` : ''}` +
|
|
767
|
+
`${c.agents.length > 0 ? ` — ${inline(c.agents)}` : ''}` +
|
|
768
|
+
`${c.annotation ? ` _(${inline(c.annotation)})_` : ''}`,
|
|
769
|
+
),
|
|
770
|
+
),
|
|
771
|
+
);
|
|
772
|
+
}
|
|
773
|
+
return parts.join('');
|
|
774
|
+
}
|
|
775
|
+
|
|
776
|
+
/**
|
|
777
|
+
* board.json, schema 1. Deterministic: fixed key insertion order, timestamps
|
|
778
|
+
* verbatim from events, invisibles escaped as \uXXXX (round-trips through
|
|
779
|
+
* JSON.parse) — silent removal is the one thing this layer refuses to do.
|
|
780
|
+
*/
|
|
781
|
+
export function boardJson(state, board = boardOf(state)) {
|
|
782
|
+
const payload = {
|
|
783
|
+
schema: 1,
|
|
784
|
+
initiative: state.initiatives.length === 1 ? state.initiatives[0] : state.initiatives,
|
|
785
|
+
progress: {
|
|
786
|
+
percent: state.percent,
|
|
787
|
+
merged: state.merged,
|
|
788
|
+
tickets: state.ticketList.length,
|
|
789
|
+
phase: state.checkpoint?.phase ?? null,
|
|
790
|
+
},
|
|
791
|
+
paused: board.paused,
|
|
792
|
+
asks: board.asks,
|
|
793
|
+
agents: sortByKey(board.agents, (a) => a.agent),
|
|
794
|
+
lanes: Object.fromEntries(LANES.map((lane) => [lane, board.lanes.get(lane)])),
|
|
795
|
+
};
|
|
796
|
+
return jsonEscapeInvisible(JSON.stringify(payload, null, 2)) + '\n';
|
|
797
|
+
}
|
|
798
|
+
|
|
443
799
|
/** The one-line progress banner; also the H1 of PROGRESS.md. */
|
|
444
800
|
export function progressLine(state) {
|
|
445
801
|
const phase = state.checkpoint?.phase ?? null;
|
|
@@ -477,6 +833,14 @@ export function warnings(state) {
|
|
|
477
833
|
for (const [ev, n] of sortByKey([...state.unknownTypes.entries()], (e) => e[0])) {
|
|
478
834
|
out.push(`unknown event type "${inlinePlain(ev)}" x${n} — counted but not folded (newer Tyran?)`);
|
|
479
835
|
}
|
|
836
|
+
// The lane the operator meant to set is NOT set, and the id they typed is the
|
|
837
|
+
// only thing that can tell them why.
|
|
838
|
+
for (const { ticket } of state.unknownOverrides) {
|
|
839
|
+
out.push(`ticket.status for unknown ticket "${inlinePlain(ticket)}" — ignored (an override never invents a ticket)`);
|
|
840
|
+
}
|
|
841
|
+
for (const { ticket } of state.unknownErrorTickets) {
|
|
842
|
+
out.push(`error names unknown ticket "${inlinePlain(ticket)}" — the error is recorded, but not bound to a ticket`);
|
|
843
|
+
}
|
|
480
844
|
if (state.initiatives.length > 1) {
|
|
481
845
|
out.push(
|
|
482
846
|
`journal mixes ${state.initiatives.length} initiatives: ${state.initiatives.map((i) => inlinePlain(i)).join(', ')}`,
|
|
@@ -529,17 +893,54 @@ function renderState(state) {
|
|
|
529
893
|
parts.push('\n## Agents\n\n');
|
|
530
894
|
parts.push(
|
|
531
895
|
table(
|
|
532
|
-
['Agent', 'Role', 'Model', 'Ticket', 'Worktree', 'Status', 'Spawned'],
|
|
533
|
-
sortByKey(state.agents, (a) => `${a.agent} ${a.spawnTs ?? ''}`).map((a) =>
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
896
|
+
['Agent', 'Role', 'Model', 'Ticket', 'Worktree', 'Status', 'Spawned', 'Last signal'],
|
|
897
|
+
sortByKey(state.agents, (a) => `${a.agent} ${a.spawnTs ?? ''}`).map((a) => {
|
|
898
|
+
// A signal that outlived its report is stale by definition, and cannot
|
|
899
|
+
// be read here: the report deleted it at fold time (see `closeAgent`),
|
|
900
|
+
// and only running rows carry a signal at all. The filter alone was not
|
|
901
|
+
// enough — a re-spawned name is running again.
|
|
902
|
+
const signal = a.status === 'running' ? state.progressByAgent.get(a.agent) : null;
|
|
903
|
+
return [
|
|
904
|
+
inline(a.agent),
|
|
905
|
+
inline(a.role),
|
|
906
|
+
inline(a.model),
|
|
907
|
+
inline(a.ticket),
|
|
908
|
+
inline(a.worktree),
|
|
909
|
+
a.status === 'running'
|
|
910
|
+
? '**running (no report yet)**'
|
|
911
|
+
: `${inline(a.status)}${a.verdict == null ? '' : `: ${inline(a.verdict)}`}`,
|
|
912
|
+
inline(a.spawnTs),
|
|
913
|
+
signal ? `${inline(signal.state)} at ${inline(signal.ts)}` : inline(null),
|
|
914
|
+
];
|
|
915
|
+
}),
|
|
916
|
+
),
|
|
917
|
+
);
|
|
918
|
+
|
|
919
|
+
parts.push('\n## Open blockages\n\n');
|
|
920
|
+
parts.push(
|
|
921
|
+
table(
|
|
922
|
+
['Ticket', 'Agent', 'Detail', 'Since'],
|
|
923
|
+
sortByKey([...state.blockages.values()], (b) => `${b.ticket ?? ''} ${b.agent}`).map((b) => [
|
|
924
|
+
inline(b.ticket),
|
|
925
|
+
inline(b.agent),
|
|
926
|
+
inline(b.detail),
|
|
927
|
+
inline(b.ts),
|
|
928
|
+
]),
|
|
929
|
+
),
|
|
930
|
+
);
|
|
931
|
+
|
|
932
|
+
parts.push('\n## Findings\n\n');
|
|
933
|
+
parts.push(
|
|
934
|
+
table(
|
|
935
|
+
['Id', 'Area', 'Claim', 'Proof', 'Ticket', 'By', 'At'],
|
|
936
|
+
state.findings.map((f) => [
|
|
937
|
+
inline(f.id),
|
|
938
|
+
inline(f.area),
|
|
939
|
+
inline(f.claim),
|
|
940
|
+
inline(f.proof),
|
|
941
|
+
inline(f.ticket),
|
|
942
|
+
inline(f.actor),
|
|
943
|
+
inline(f.ts),
|
|
543
944
|
]),
|
|
544
945
|
),
|
|
545
946
|
);
|
|
@@ -718,10 +1119,16 @@ function renderProgress(state) {
|
|
|
718
1119
|
*/
|
|
719
1120
|
export function renderProjections(readResult) {
|
|
720
1121
|
const state = fold(readResult);
|
|
1122
|
+
const board = boardOf(state);
|
|
721
1123
|
return {
|
|
722
1124
|
state,
|
|
723
1125
|
warnings: warnings(state),
|
|
724
|
-
files: {
|
|
1126
|
+
files: {
|
|
1127
|
+
[STATE_FILE]: renderState(state),
|
|
1128
|
+
[PROGRESS_FILE]: renderProgress(state),
|
|
1129
|
+
[BOARD_FILE]: renderBoard(state, board),
|
|
1130
|
+
[BOARD_JSON_FILE]: boardJson(state, board),
|
|
1131
|
+
},
|
|
725
1132
|
};
|
|
726
1133
|
}
|
|
727
1134
|
|
package/skills/run/SKILL.md
CHANGED
|
@@ -138,8 +138,11 @@ open one.
|
|
|
138
138
|
`.tyran/state/<initiative>/journal.jsonl`:
|
|
139
139
|
`node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs append <journal> <event>
|
|
140
140
|
<initiative> --actor conductor --data '{...}'`. Regenerate the readable
|
|
141
|
-
views with `scripts/project.mjs
|
|
142
|
-
|
|
141
|
+
views with `scripts/project.mjs` at every merge — `BOARD.md` and
|
|
142
|
+
`board.json` are part of the set — and the cross-initiative board with
|
|
143
|
+
`scripts/board.mjs`; every one of them is GENERATED — never hand-edit.
|
|
144
|
+
Moving a ticket on the board IS appending an event; there is no other way.
|
|
145
|
+
Authored, alongside the journal:
|
|
143
146
|
`PLAN.md` (decomposition plus the **manifest of
|
|
144
147
|
shared zones**) and `NOTES.md` (side observations, defaults you adopted,
|
|
145
148
|
and **signals about the PROCESS itself**: what slowed the work, what the
|
|
@@ -164,10 +167,28 @@ open one.
|
|
|
164
167
|
list: decide and record. Without this you ask a second time for consent
|
|
165
168
|
you already have, which is the most common reason an operator ends up
|
|
166
169
|
chasing you instead of reading reports.
|
|
170
|
+
- **Operator messages mid-run queue; none is dropped silently.** Triage
|
|
171
|
+
each at the next natural pause: which initiative (or a new one), what
|
|
172
|
+
size, then a `ticket.created` carrying `id` — the one key `append` does
|
|
173
|
+
NOT issue for you, so read it from the journal and never from memory:
|
|
174
|
+
`journal.mjs next-id <abs-journal> T` returns the next one, continuing
|
|
175
|
+
the plan's numbering — plus `title`, `deps` and `files_predicted`; or a
|
|
176
|
+
`decision` when it changes course rather than adds work. Confirm in one
|
|
177
|
+
line — "queued as T-9". A thought that never reached the journal does
|
|
178
|
+
not exist. `ticket.status` is your lane override for the three states no
|
|
179
|
+
lifecycle event can derive (`blocked`, `waiting-operator`, `parked`);
|
|
180
|
+
the next report, review or merge clears it.
|
|
181
|
+
- **Scout `DURABLE:` findings, you journal** as `finding` events — the
|
|
182
|
+
required keys are `area` + `claim` (the area is the path or subsystem the
|
|
183
|
+
scout's proof points at), plus that `proof` — scouts write nothing
|
|
184
|
+
themselves. Implementers and reviewers append their own.
|
|
167
185
|
2. **Fresh context per task.** Handoffs are SELF-CONTAINED; the agent
|
|
168
186
|
disappears afterwards. Never ask the operator to compact. **Every handoff
|
|
169
187
|
carries eight things:** (1) the role and one story, one goal; (2) paths to
|
|
170
|
-
the files of record
|
|
188
|
+
the files of record — including the ABSOLUTE path of the initiative
|
|
189
|
+
journal in the MAIN checkout and the initiative slug, because worktree
|
|
190
|
+
agents append their `progress` and `finding` events there;
|
|
191
|
+
(3) the iron rules copied VERBATIM, not linked;
|
|
171
192
|
(4) the lease protocol (rule 7); (5) the **evidence contract** — the report
|
|
172
193
|
must contain raw command output (exit codes, `X passed / Y failed`); a
|
|
173
194
|
paraphrase like "tests are green" with no log is a REJECTED report. Final
|
|
@@ -252,6 +273,12 @@ open one.
|
|
|
252
273
|
(XL); product, visual and irreversible decisions, put in plain language
|
|
253
274
|
with your recommendation; anything hard to undo or visible outside the
|
|
254
275
|
repo. **"Shall I continue?" is forbidden.**
|
|
276
|
+
**Every question to the operator lands in the journal before (or as) you
|
|
277
|
+
ask it**: a `gate` event, `result: WAITING_ON_OPERATOR`, `data` carrying
|
|
278
|
+
`question`, `recommendation`, `default` and `ticket` when it has one — a
|
|
279
|
+
question that lives only in chat has to be re-litigated after every
|
|
280
|
+
compaction. When answered, append the same `kind` with `result: answered`
|
|
281
|
+
plus a `decision` recording the answer in the operator's words.
|
|
255
282
|
**Check the brake before every spawn and every merge:**
|
|
256
283
|
`node ${CLAUDE_PLUGIN_ROOT}/scripts/stop-check.mjs` — exit 1 means the
|
|
257
284
|
operator created `.tyran/STOP`. Halt, report where you got to, and do not
|
package/skills/status/SKILL.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Where is the work right now. Regenerates
|
|
2
|
+
description: Where is the work right now. Regenerates the projections and the kanban board from the journal and answers with the progress line, the agents still running, the open gates and the resume steps. Read-only. Use for /tyran:status or when asked what is going on.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Status
|
|
@@ -9,6 +9,7 @@ Answer from the journal, never from memory.
|
|
|
9
9
|
```bash
|
|
10
10
|
J=$(ls -t .tyran/state/*/journal.jsonl 2>/dev/null | head -1)
|
|
11
11
|
node "${CLAUDE_PLUGIN_ROOT}/scripts/project.mjs" "$J" --out-dir "$(dirname "$J")"
|
|
12
|
+
node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" --dir .tyran
|
|
12
13
|
node "${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs" tail "$J"
|
|
13
14
|
node "${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs" open-spawns "$J"
|
|
14
15
|
```
|
|
@@ -28,6 +29,9 @@ Then report, in this order and no longer than a screen:
|
|
|
28
29
|
these; they mean two agents believed they owned the same worktree.
|
|
29
30
|
6. The resume steps from the last checkpoint.
|
|
30
31
|
|
|
32
|
+
End by pointing the operator at `.tyran/state/board.html` — the kanban view
|
|
33
|
+
of everything above, refreshed on every subagent stop and every merge.
|
|
34
|
+
|
|
31
35
|
If there is no journal, say exactly that and suggest `/tyran:setup`. Do not
|
|
32
36
|
reconstruct a status from the git log — a plausible status is worse than none,
|
|
33
37
|
because it will be believed.
|