@jjanczur/tyran 0.1.32 → 0.1.33
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 +67 -0
- package/README.md +1 -1
- package/package.json +1 -1
- package/scripts/board-html.mjs +83 -0
- package/scripts/board.mjs +38 -0
- package/scripts/overnight.mjs +24 -2
- package/skills/run/SKILL.md +26 -0
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
{
|
|
12
12
|
"name": "tyran",
|
|
13
13
|
"description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
|
|
14
|
-
"version": "0.1.
|
|
14
|
+
"version": "0.1.33",
|
|
15
15
|
"source": "./",
|
|
16
16
|
"author": {
|
|
17
17
|
"name": "Jacek Janczura",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.33",
|
|
4
4
|
"description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Jacek Janczura",
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,72 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.33 — 2026-08-17
|
|
4
|
+
|
|
5
|
+
### The board was hiding what its own journal already knew
|
|
6
|
+
|
|
7
|
+
Three directory slugs and one blended percentage. The journal has carried a
|
|
8
|
+
written title since it existed — "The kanban board: one screen that answers
|
|
9
|
+
what is going on" — and `crossBoard` summed every initiative's progress before
|
|
10
|
+
throwing the parts away, so an operator reading "47%" across three slugs could
|
|
11
|
+
not tell which was nearly done from which had not started.
|
|
12
|
+
|
|
13
|
+
Each initiative now has its own row: title, progress, and how many questions
|
|
14
|
+
it is waiting on. The payload reads no clock — it ships `last_ts` and the page
|
|
15
|
+
ages it — so `board.mjs --check` stays byte-exact.
|
|
16
|
+
|
|
17
|
+
**This replaced an archive feature, on measurement.** Across 63 distinct real
|
|
18
|
+
journals only 6 were finished-and-archivable while **43 were waiting on a
|
|
19
|
+
question nobody had answered**. The board was never cluttered with completed
|
|
20
|
+
work; it was full of ABANDONED work. Archiving would have touched under 10% of
|
|
21
|
+
initiatives, left the 64-initiative ceiling exactly where it is, and — since
|
|
22
|
+
archivable means 100% merged — pulled the headline percentage DOWN.
|
|
23
|
+
|
|
24
|
+
**Upgrading: one expected `--check` drift.** The payload gains a top-level
|
|
25
|
+
`initiatives` key, so a `board.json` committed by an earlier version no longer
|
|
26
|
+
matches what this one generates. Measured: `board.mjs --check` exits 1 once on
|
|
27
|
+
an upgraded install and 0 after a single regenerate —
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
node scripts/board.mjs --dir .tyran # then commit the three artefacts
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`doctor --state` is silent about it either way; the only surface is an
|
|
34
|
+
explicit `--check`, which matters if you run one in CI. The board `schema`
|
|
35
|
+
stays 1 because nothing about the existing keys changed, the same call made
|
|
36
|
+
when `errors_logged` was added.
|
|
37
|
+
|
|
38
|
+
### Two more things that had never worked and said nothing
|
|
39
|
+
|
|
40
|
+
- **`/run.json` never carried a reset time.** `pickWindow` tested
|
|
41
|
+
`typeof resets_at === 'string'` while every writer produces epoch SECONDS,
|
|
42
|
+
so it returned null for every real payload it was ever given: the run panel
|
|
43
|
+
could say a pause was in force but never when it would end. Live since the
|
|
44
|
+
feature shipped.
|
|
45
|
+
- **The closing checkpoint had no producer.** The projection has closed every
|
|
46
|
+
still-open spawn on `checkpoint phase=closed` since 0.1.31, and nothing ever
|
|
47
|
+
emitted one — 9 of 63 real journals had one. So an agent that finished weeks
|
|
48
|
+
ago still read as live work. The conductor is now told to write it, including
|
|
49
|
+
when an initiative ends because it was ABANDONED, and the test executes the
|
|
50
|
+
command rather than grepping for it.
|
|
51
|
+
|
|
52
|
+
`runState` also reports `limits_mode`: "the gate cannot see" and "the feature
|
|
53
|
+
was never switched on" are different facts with the same symptom.
|
|
54
|
+
|
|
55
|
+
### An ask offers its recommendation as one click
|
|
56
|
+
|
|
57
|
+
It was shown as text, and the only way to accept it was to retype it into the
|
|
58
|
+
box beneath it. For an operator who is not an engineer, that gap was most of
|
|
59
|
+
the difficulty of the page. The button fills the box rather than submitting,
|
|
60
|
+
so the wording stays editable and the answer stays deliberate.
|
|
61
|
+
|
|
62
|
+
### Findings are pointed at, not copied
|
|
63
|
+
|
|
64
|
+
Measured across 63 distinct journals: 3 carry any finding, 49 in total, and
|
|
65
|
+
none names a ticket — so they cannot enrich a card. Median claim is 429
|
|
66
|
+
characters and `STATE.md` already renders the full table. The initiative row
|
|
67
|
+
carries a count when it is non-zero and nothing else; a test forbids `claim`
|
|
68
|
+
or `proof` reaching the byte-compared payload.
|
|
69
|
+
|
|
3
70
|
## 0.1.32 — 2026-08-17
|
|
4
71
|
|
|
5
72
|
### Overnight mode could never fire, on any install
|
package/README.md
CHANGED
|
@@ -309,7 +309,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
|
|
|
309
309
|
fires and who invokes it, is in
|
|
310
310
|
[skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
|
|
311
311
|
themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
|
|
312
|
-
it:
|
|
312
|
+
it: 1535 unit tests, run with `node --test "tests/**/*.test.mjs"`.
|
|
313
313
|
|
|
314
314
|
## Documentation
|
|
315
315
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jjanczur/tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.33",
|
|
4
4
|
"description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
package/scripts/board-html.mjs
CHANGED
|
@@ -195,6 +195,20 @@ pre.how .c{color:var(--muted)}
|
|
|
195
195
|
input against the 5-minute write's 1.25x. Without a distinct colour the
|
|
196
196
|
most expensive caching decision on the page is invisible. */
|
|
197
197
|
.comp .s-cache_write_1h{background:var(--ink)}
|
|
198
|
+
/* ---- initiatives ---- */
|
|
199
|
+
.inits{display:flex;flex-direction:column;gap:.3rem;margin:.5rem 0}
|
|
200
|
+
.initrow{display:grid;grid-template-columns:minmax(0,1.6fr) 5rem auto minmax(0,1fr);
|
|
201
|
+
gap:.6rem;align-items:center;padding:.35rem .5rem;border-radius:4px}
|
|
202
|
+
/* An initiative nobody can move without the operator is the one thing on this
|
|
203
|
+
section worth catching an eye. */
|
|
204
|
+
.initrow.waiting{background:color-mix(in srgb,var(--brass) 12%,transparent)}
|
|
205
|
+
.initrow .il{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
|
|
206
|
+
.initrow .islug{color:var(--muted);margin-left:.4rem;font-size:.85em}
|
|
207
|
+
.initrow .ib{height:6px;background:var(--line);border-radius:3px;overflow:hidden}
|
|
208
|
+
.initrow .ib i{display:block;height:100%;background:var(--sage)}
|
|
209
|
+
.initrow .iv,.initrow .iw{color:var(--muted);font-size:.9em;white-space:nowrap}
|
|
210
|
+
.initrow .iw.warn{color:var(--brass);font-weight:600}
|
|
211
|
+
|
|
198
212
|
/* ---- the per-day series ---- */
|
|
199
213
|
.days{display:flex;align-items:flex-end;gap:2px;height:74px;margin:.5rem 0 .3rem;
|
|
200
214
|
overflow-x:auto;padding-bottom:2px}
|
|
@@ -572,6 +586,59 @@ if (data.schema !== 1) {
|
|
|
572
586
|
ov.appendChild(first);
|
|
573
587
|
}
|
|
574
588
|
|
|
589
|
+
// ---- initiatives, and the ones that have stopped moving ----------------
|
|
590
|
+
//
|
|
591
|
+
// MEASURED, and the reason this section exists rather than an archive: of 63
|
|
592
|
+
// real journals, 43 were waiting on a question nobody answered and only 6
|
|
593
|
+
// were finished-and-archivable. The board was not cluttered with completed
|
|
594
|
+
// work; it was full of ABANDONED work, and archiving the finished 6 would
|
|
595
|
+
// have removed the only initiatives at 100% and pulled the headline
|
|
596
|
+
// percentage down.
|
|
597
|
+
//
|
|
598
|
+
// "Waiting" is the initiative's own count of open operator questions. The
|
|
599
|
+
// idle time is computed HERE, from last_ts, because the payload is
|
|
600
|
+
// byte-compared and reads no clock — the same split the agent strip uses.
|
|
601
|
+
var inits = Array.isArray(data.initiatives) ? data.initiatives : [];
|
|
602
|
+
if (inits.length > 0) {
|
|
603
|
+
var stalled = inits.filter(function (i) { return i.waiting > 0; }).sort(function (a, b) {
|
|
604
|
+
return (ageMsOf(b.last_ts) || 0) - (ageMsOf(a.last_ts) || 0);
|
|
605
|
+
});
|
|
606
|
+
ov.appendChild(el('h2', null, 'Initiatives'));
|
|
607
|
+
if (stalled.length > 0) {
|
|
608
|
+
ov.appendChild(el('div', 'hint',
|
|
609
|
+
stalled.length + ' of ' + inits.length + ' are waiting on an answer from you. ' +
|
|
610
|
+
'Longest-waiting first — an initiative with an open question does not move until it is answered.'));
|
|
611
|
+
}
|
|
612
|
+
var table = el('div', 'inits');
|
|
613
|
+
var ordered = stalled.concat(inits.filter(function (i) { return !(i.waiting > 0); }));
|
|
614
|
+
ordered.forEach(function (i) {
|
|
615
|
+
var row = el('div', i.waiting > 0 ? 'initrow waiting' : 'initrow');
|
|
616
|
+
// The TITLE, which the journal has carried all along while this page
|
|
617
|
+
// showed a directory slug.
|
|
618
|
+
var label = el('div', 'il');
|
|
619
|
+
label.appendChild(el('b', null, i.title || i.name));
|
|
620
|
+
if (i.title) label.appendChild(el('span', 'islug', i.name));
|
|
621
|
+
row.appendChild(label);
|
|
622
|
+
var bar = el('div', 'ib');
|
|
623
|
+
var fill = el('i');
|
|
624
|
+
fill.style.width = (typeof i.percent === 'number' ? i.percent : 0) + '%';
|
|
625
|
+
bar.appendChild(fill);
|
|
626
|
+
row.appendChild(bar);
|
|
627
|
+
var counts = i.merged + '/' + i.tickets + ' merged';
|
|
628
|
+
// Named only when there is something to name. A findings count of zero
|
|
629
|
+
// on every row is noise that teaches the eye to skip the column.
|
|
630
|
+
if (i.findings > 0) counts += ' \u00b7 ' + i.findings + ' finding' + (i.findings === 1 ? '' : 's');
|
|
631
|
+
row.appendChild(el('div', 'iv', counts));
|
|
632
|
+
var age = ageMsOf(i.last_ts);
|
|
633
|
+
row.appendChild(el('div', i.waiting > 0 ? 'iw warn' : 'iw',
|
|
634
|
+
i.waiting > 0
|
|
635
|
+
? i.waiting + ' waiting on you \u00b7 quiet ' + ago(i.last_ts)
|
|
636
|
+
: (age === null ? '' : 'last moved ' + ago(i.last_ts))));
|
|
637
|
+
table.appendChild(row);
|
|
638
|
+
});
|
|
639
|
+
ov.appendChild(table);
|
|
640
|
+
}
|
|
641
|
+
|
|
575
642
|
ov.appendChild(el('h2', null, 'Agents'));
|
|
576
643
|
// Named, not implied by the order: the strip is sorted stalest-first by the
|
|
577
644
|
// server, and a reader who does not know that reads the first chip as the
|
|
@@ -805,6 +872,21 @@ if (data.schema !== 1) {
|
|
|
805
872
|
send.setAttribute('type', 'button');
|
|
806
873
|
var useDefault = hasDefault ? el('button', 'sbtn', 'Take the default') : null;
|
|
807
874
|
if (useDefault) useDefault.setAttribute('type', 'button');
|
|
875
|
+
// The recommendation was already shown, as TEXT, and the only way to
|
|
876
|
+
// accept it was to retype it into the box below it. For an operator who
|
|
877
|
+
// is not an engineer that gap is most of the difficulty of the whole
|
|
878
|
+
// page: the agent has said what it thinks should happen and the human is
|
|
879
|
+
// asked to transcribe it. This fills the box instead of submitting, so
|
|
880
|
+
// the wording stays editable and the answer is still deliberate.
|
|
881
|
+
var useRec = a.recommendation ? el('button', 'sbtn', 'Use the recommendation') : null;
|
|
882
|
+
if (useRec) {
|
|
883
|
+
useRec.setAttribute('type', 'button');
|
|
884
|
+
useRec.addEventListener('click', function () {
|
|
885
|
+
input.value = a.recommendation;
|
|
886
|
+
input.focus();
|
|
887
|
+
holdRefresh();
|
|
888
|
+
});
|
|
889
|
+
}
|
|
808
890
|
var status = el('div', 'sstat');
|
|
809
891
|
|
|
810
892
|
var submit = function (text) {
|
|
@@ -847,6 +929,7 @@ if (data.schema !== 1) {
|
|
|
847
929
|
|
|
848
930
|
box.appendChild(input);
|
|
849
931
|
acts.appendChild(send);
|
|
932
|
+
if (useRec) acts.appendChild(useRec);
|
|
850
933
|
if (useDefault) acts.appendChild(useDefault);
|
|
851
934
|
box.appendChild(acts);
|
|
852
935
|
box.appendChild(status);
|
package/scripts/board.mjs
CHANGED
|
@@ -234,6 +234,7 @@ export const MAX_LOGGED_ERRORS = 20;
|
|
|
234
234
|
|
|
235
235
|
export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
|
|
236
236
|
const asks = [];
|
|
237
|
+
const summaries = [];
|
|
237
238
|
const agents = [];
|
|
238
239
|
const paused = [];
|
|
239
240
|
const logged = [];
|
|
@@ -246,6 +247,39 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
|
|
|
246
247
|
for (const { name, state, board, files: docs } of initiatives) {
|
|
247
248
|
merged += state.merged;
|
|
248
249
|
tickets += state.ticketList.length;
|
|
250
|
+
// Per-initiative, because one blended percentage over every initiative is
|
|
251
|
+
// not a fact about any of them: an operator reading "50%" across four
|
|
252
|
+
// slugs cannot tell which is nearly done from which has not started.
|
|
253
|
+
//
|
|
254
|
+
// The TITLE is the point of the row. `init.created` has carried a written
|
|
255
|
+
// sentence all along — "Settings on the board: edit config and the
|
|
256
|
+
// autonomy policy from the page" — and the board showed the directory
|
|
257
|
+
// slug. `waiting` and `last_ts` are here rather than a computed idle time
|
|
258
|
+
// because this payload is byte-compared under `--check` and reads no
|
|
259
|
+
// clock; the page ages them, exactly as it already ages agents.
|
|
260
|
+
summaries.push({
|
|
261
|
+
name,
|
|
262
|
+
title: typeof state.created?.data?.title === 'string' ? state.created.data.title : null,
|
|
263
|
+
tickets: state.ticketList.length,
|
|
264
|
+
merged: state.merged,
|
|
265
|
+
percent: state.percent,
|
|
266
|
+
waiting: board.asks.length,
|
|
267
|
+
// A COUNT, and deliberately not the findings themselves. Measured across
|
|
268
|
+
// 63 distinct real journals: 3 carry any finding at all, 49 in total,
|
|
269
|
+
// and NOT ONE names a ticket — so they cannot enrich a card, which is
|
|
270
|
+
// where a richer board would have put them. Their median claim is 429
|
|
271
|
+
// characters, a paragraph rather than a label, and STATE.md already
|
|
272
|
+
// renders the full seven-column table.
|
|
273
|
+
//
|
|
274
|
+
// So this is a pointer, not a copy: the research exists and the reader
|
|
275
|
+
// is told where. Duplicating the prose here would be ADR-21's defect
|
|
276
|
+
// and would cost ~600 B per finding in a byte-compared payload.
|
|
277
|
+
// Guarded: `crossBoard` is exported and takes any folded state, and a
|
|
278
|
+
// caller assembling one by hand need not have every collection. A
|
|
279
|
+
// missing array must read as "none", never take the board down.
|
|
280
|
+
findings: (state.findings ?? []).length,
|
|
281
|
+
last_ts: state.lastTs,
|
|
282
|
+
});
|
|
249
283
|
if (state.lastTs !== null && (asOf === null || state.lastTs > asOf)) asOf = state.lastTs;
|
|
250
284
|
for (const a of board.asks) asks.push({ ...a, init: name });
|
|
251
285
|
for (const a of board.agents) agents.push({ ...a, init: name });
|
|
@@ -329,6 +363,10 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
|
|
|
329
363
|
stop: stop === null ? null : { stopped: stop.stopped, reason: stop.reason },
|
|
330
364
|
paused,
|
|
331
365
|
asks,
|
|
366
|
+
// Ordered by directory name, like everything else here, so two renders of
|
|
367
|
+
// one journal set are byte-identical. `totals.percent` blends these; the
|
|
368
|
+
// rows are what let a reader see WHICH initiative it blends.
|
|
369
|
+
initiatives: summaries,
|
|
332
370
|
agents,
|
|
333
371
|
files,
|
|
334
372
|
lanes,
|
package/scripts/overnight.mjs
CHANGED
|
@@ -228,15 +228,37 @@ export function runState(repo, nowMs = Date.now()) {
|
|
|
228
228
|
five_hour: pickWindow(sidecar.five_hour),
|
|
229
229
|
seven_day: pickWindow(sidecar.seven_day),
|
|
230
230
|
},
|
|
231
|
+
// Which mode the gate is IN, not only what it can see. Without this a page
|
|
232
|
+
// cannot tell "the gate cannot see" from "the feature was never switched
|
|
233
|
+
// on", and off is the default (templates/config.yaml) — so a telemetry
|
|
234
|
+
// warning built on the `usage` field alone would fire on every repository
|
|
235
|
+
// that has never enabled overnight mode.
|
|
236
|
+
limits_mode: readLimitsFile(repo)?.mode ?? 'off',
|
|
231
237
|
};
|
|
232
238
|
}
|
|
233
239
|
|
|
234
|
-
/**
|
|
240
|
+
/**
|
|
241
|
+
* Numbers and an ISO string only — never a free payload string from a hook.
|
|
242
|
+
*
|
|
243
|
+
* `resets_at` arrives as epoch SECONDS: `statusline.mjs`'s `windowOf` keeps
|
|
244
|
+
* only `finiteNumber` values, and `usage-source.mjs` normalises the platform's
|
|
245
|
+
* ISO string to the same. This function tested `typeof === 'string'` and so
|
|
246
|
+
* returned null for every real payload it has ever been given — `/run.json`
|
|
247
|
+
* has never once carried a reset time, and the board's run panel could say a
|
|
248
|
+
* pause was in force but never when it would end.
|
|
249
|
+
*
|
|
250
|
+
* The string half of the guard was not wrong about the OUTPUT: this is the
|
|
251
|
+
* page's shape, and an ISO string is what a reader wants. It was wrong about
|
|
252
|
+
* the input. So convert, rather than widening the test and emitting seconds
|
|
253
|
+
* the page would have to know to multiply.
|
|
254
|
+
*/
|
|
235
255
|
function pickWindow(w) {
|
|
236
256
|
if (w === null || typeof w !== 'object') return null;
|
|
257
|
+
const seconds = typeof w.resets_at === 'number' && Number.isFinite(w.resets_at) ? w.resets_at : null;
|
|
258
|
+
const iso = seconds === null ? null : new Date(seconds * 1000);
|
|
237
259
|
return {
|
|
238
260
|
used_percentage: typeof w.used_percentage === 'number' ? w.used_percentage : null,
|
|
239
|
-
resets_at:
|
|
261
|
+
resets_at: iso !== null && Number.isFinite(iso.getTime()) ? iso.toISOString() : null,
|
|
240
262
|
};
|
|
241
263
|
}
|
|
242
264
|
|
package/skills/run/SKILL.md
CHANGED
|
@@ -452,6 +452,32 @@ open one.
|
|
|
452
452
|
a lease still held by an agent that has already reported. An orphaned lease
|
|
453
453
|
blocks the next initiative from a resource nobody is using, and the person
|
|
454
454
|
who hits it has no way to know it is stale.
|
|
455
|
+
- **Close the initiative when it is closed**, with the retrospective recorded
|
|
456
|
+
and the leases released:
|
|
457
|
+
|
|
458
|
+
```bash
|
|
459
|
+
node "${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs" append <abs-journal> checkpoint <init> \
|
|
460
|
+
--actor conductor --data '{"phase":"closed","next_steps":[]}'
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
`append ... checkpoint`, not a `checkpoint` subcommand — there is no such
|
|
464
|
+
subcommand, and the first draft of this line invented one. It would have
|
|
465
|
+
printed a usage block and closed nothing.
|
|
466
|
+
|
|
467
|
+
This is one line and it is load-bearing. The projection closes every still-
|
|
468
|
+
open spawn on a closing checkpoint, which is what stops an agent that
|
|
469
|
+
finished weeks ago from reading as live work, and it is the only signal any
|
|
470
|
+
reader has that an initiative is DONE rather than abandoned mid-flight.
|
|
471
|
+
|
|
472
|
+
Measured across 63 real journals: **9 ever received one**, while 43 sat
|
|
473
|
+
waiting on a question nobody answered. Nothing had ever told you to write
|
|
474
|
+
it — the fold that consumes it shipped, and the event that triggers it was
|
|
475
|
+
never emitted by anything, so the feature has been inert since it landed.
|
|
476
|
+
|
|
477
|
+
A closing checkpoint is not the same as "every ticket merged". Say it when
|
|
478
|
+
the work is over, including when it is over because it was abandoned — an
|
|
479
|
+
initiative someone walked away from is finished too, and saying so is what
|
|
480
|
+
keeps the board honest about which of them are still waiting on you.
|
|
455
481
|
- **A usage-gate refusal is a wind-down order, not an obstacle.** Near the
|
|
456
482
|
subscription window the gate refuses everything except checkpointing;
|
|
457
483
|
its refusal text IS the checklist — follow it verbatim, in order, then
|