@jjanczur/tyran 0.1.10 → 0.1.11
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 +24 -0
- 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/package.json +1 -1
- package/scripts/doctor.mjs +41 -2
- package/scripts/journal.mjs +73 -2
- package/scripts/project.mjs +178 -24
- package/skills/run/SKILL.md +25 -1
|
@@ -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.11",
|
|
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.11",
|
|
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,29 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.11 — 2026-08-13
|
|
4
|
+
|
|
5
|
+
### The journal learns what agents are doing, finding, and waiting on
|
|
6
|
+
|
|
7
|
+
The closed event set grows 14 → 17 — the reviewed core change the journal
|
|
8
|
+
page names. `progress` is the agent's own mid-run signal (`started` ·
|
|
9
|
+
`working` · `blocked` · `unblocked`, a closed list emitted at four named
|
|
10
|
+
points, never part of spawn↔report pairing); `finding` is a claim about a named
|
|
11
|
+
area plus the proof for it, queryable by other agents (`F-<n>` ids issued
|
|
12
|
+
by `append`);
|
|
13
|
+
`ticket.status` is the conductor's lane override for exactly the three
|
|
14
|
+
states no lifecycle event can derive (`blocked` · `waiting-operator` ·
|
|
15
|
+
`parked`), cleared automatically by the next report, review or merge and
|
|
16
|
+
never counted as progress. Both new value sets are closed and rejected at
|
|
17
|
+
append naming the whole set; the free-text keys `detail`/`claim`/`proof`
|
|
18
|
+
cap at 2 000 codepoints — rejected, never truncated.
|
|
19
|
+
|
|
20
|
+
STATE.md gains `Open blockages` and `Findings` sections and a per-agent
|
|
21
|
+
`Last signal` column; doctor gains `spawn-blocked` (an agent whose own last
|
|
22
|
+
signal says blocked, past a threshold); the agent contracts gain the
|
|
23
|
+
emission points, the anti-duplication grep, and the implementer's "what you
|
|
24
|
+
did NOT do" report section; operator questions and mid-run ticket intake
|
|
25
|
+
now land as journal events, so the coming board can render them.
|
|
26
|
+
|
|
3
27
|
## 0.1.10 — 2026-08-13
|
|
4
28
|
|
|
5
29
|
### Overnight mode: the usage cliff becomes a wind-down
|
package/agents/implementer.md
CHANGED
|
@@ -15,6 +15,21 @@ commits and anything written to disk are in English.**
|
|
|
15
15
|
lease file as the handoff describes. Another agent's unexpired lease
|
|
16
16
|
means you do NOT start — you report back. Release it when you finish,
|
|
17
17
|
including when you finish by failing.
|
|
18
|
+
- **Signal at four points, no more** — `progress` events appended to the
|
|
19
|
+
MAIN checkout's journal (the handoff carries its absolute path):
|
|
20
|
+
`started` right after the lease (it is also the proof the lease protocol
|
|
21
|
+
was honoured) · `blocked` at the FIRST blockage, BEFORE attempting any
|
|
22
|
+
workaround · `unblocked` when it clears · `working` before the final
|
|
23
|
+
full validation run, the longest silent stretch you have. Shape:
|
|
24
|
+
`node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs append <abs-journal>
|
|
25
|
+
progress <init> --actor <you> --data
|
|
26
|
+
'{"agent":"<you>","state":"blocked","ticket":"T-n","detail":"..."}'`.
|
|
27
|
+
Four emissions per story; this is a closed list, not a diary.
|
|
28
|
+
- **Grep before you build.** Search for an existing implementation of the
|
|
29
|
+
thing you are about to write; if it exists, report it as a corrected
|
|
30
|
+
premise instead of duplicating it. Durable discoveries worth another
|
|
31
|
+
agent's time go into the journal as `finding` events (`area` + `claim`
|
|
32
|
+
are required, plus its `proof`) — not only into prose.
|
|
18
33
|
- **Verify the handoff's premises in the code.** A stale path, a wrong
|
|
19
34
|
assignment, a function that no longer exists — correct it and report the
|
|
20
35
|
correction EXPLICITLY instead of executing blindly. Premises about DATA
|
|
@@ -54,9 +69,11 @@ commits and anything written to disk are in English.**
|
|
|
54
69
|
and showing it still fails — not by asserting it. Take that baseline
|
|
55
70
|
after a `git fetch` run immediately beforehand; a stale remote once
|
|
56
71
|
turned a correct proof into a false accusation.
|
|
57
|
-
7. **Final report:** what was done ·
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
72
|
+
7. **Final report:** what was done · **what you did NOT do** (scope cut,
|
|
73
|
+
tests skipped, the input class you never exercised — name the worst case
|
|
74
|
+
for each, this section is a merge gate) · test and validation output ·
|
|
75
|
+
what the optimization pass changed · branch or PR · premises you
|
|
76
|
+
corrected · a verdict on every knowledge-brief entry id in your handoff
|
|
77
|
+
(helped, wrong, or unused — the retrospective folds these into the
|
|
78
|
+
store's counters) · open doubts. The open doubts are worth more than the
|
|
79
|
+
summary; do not tidy them away.
|
package/agents/retro.md
CHANGED
|
@@ -17,6 +17,10 @@ to disk is in English.**
|
|
|
17
17
|
the process itself).
|
|
18
18
|
2. The agents' reports from this initiative: corrected premises, escalations,
|
|
19
19
|
open doubts. This is the densest source of signal you have.
|
|
20
|
+
Alongside them, the journal's `finding` events (`journal.mjs query <file>
|
|
21
|
+
--ev finding`) — the claims agents recorded WITH proof, mid-run. Promote
|
|
22
|
+
the recurring ones into `.tyran/knowledge/` through the filter below; the
|
|
23
|
+
rest die with the initiative, which is correct.
|
|
20
24
|
3. `git log` for the initiative: reverts, fixes of your own regressions,
|
|
21
25
|
repeated phases.
|
|
22
26
|
4. The current state of `skills/`, `agents/`, `scripts/` and the docs — **so
|
package/agents/reviewer.md
CHANGED
|
@@ -25,6 +25,10 @@ that keeps you.
|
|
|
25
25
|
author's report with no raw command output you reject on sight, without
|
|
26
26
|
reading further. Run the tests yourself; for UI, drive the browser yourself
|
|
27
27
|
through `browser-check`. Paste what you got, with counts.
|
|
28
|
+
- **Signal `started` after taking your lease, `blocked`/`unblocked` when a
|
|
29
|
+
blockage genuinely stops the review** — `progress` events to the main
|
|
30
|
+
checkout's journal, path from the handoff. No `working` signal: your
|
|
31
|
+
`review` event is your completion, and it closes your spawn.
|
|
28
32
|
- Settle disputed measurements (font size, padding, colour) by dumping
|
|
29
33
|
computed styles to JSON, never by eye. An "it looks off" audit produces
|
|
30
34
|
wrong findings at roughly the rate it produces right ones.
|
package/agents/scout.md
CHANGED
|
@@ -17,7 +17,10 @@ disk is in English.**
|
|
|
17
17
|
2. **A finding is a claim plus its proof.** Every line you return is
|
|
18
18
|
`finding -> path:line, quoted fragment, or URL`. The conductor reads dozens
|
|
19
19
|
of these; there is no budget for warm-up paragraphs, and an unsourced
|
|
20
|
-
finding costs more than no finding because someone will act on it.
|
|
20
|
+
finding costs more than no finding because someone will act on it. Prefix
|
|
21
|
+
the ones that will outlive this task with `DURABLE:` — the conductor
|
|
22
|
+
journals those as `finding` events (rule 1 stands: you write nothing, not
|
|
23
|
+
even to the journal; the prefix is how a durable fact reaches it anyway).
|
|
21
24
|
3. **When you did not find something, say "I did not find it"** and list
|
|
22
25
|
where you looked. Never fill the gap with a guess. Anchor every grep over
|
|
23
26
|
env or config files (`grep -nE '^VARIABLE='`) — an unanchored grep matches
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jjanczur/tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.11",
|
|
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/doctor.mjs
CHANGED
|
@@ -154,6 +154,7 @@ export const SEVERITY_BY_CODE = Object.freeze(
|
|
|
154
154
|
// spawns
|
|
155
155
|
'spawn-open': 'info',
|
|
156
156
|
'spawn-stale': 'warning',
|
|
157
|
+
'spawn-blocked': 'warning',
|
|
157
158
|
'spawn-duplicate': 'warning',
|
|
158
159
|
'spawn-orphan-report': 'warning',
|
|
159
160
|
'agent-name-unusable': 'warning',
|
|
@@ -674,14 +675,50 @@ function closeSpawnHint(journalPath, init, agent) {
|
|
|
674
675
|
: `node scripts/journal.mjs close-spawn ${sq(journalPath)} ${sq(slug)} ${sq(agent)} --reason "<why>"`;
|
|
675
676
|
}
|
|
676
677
|
|
|
678
|
+
/** How long a self-reported `blocked` may stand before it is a finding. */
|
|
679
|
+
export const DEFAULT_BLOCKED_HOURS = 1;
|
|
680
|
+
|
|
681
|
+
/** The latest `progress` signal per agent, from the raw events. */
|
|
682
|
+
function lastSignals(events) {
|
|
683
|
+
const signals = new Map();
|
|
684
|
+
for (const e of events) {
|
|
685
|
+
if (e?.ev === 'progress' && typeof e?.data?.agent === 'string') {
|
|
686
|
+
signals.set(e.data.agent, { state: e.data.state ?? null, detail: e.data.detail ?? null, ts: e.ts ?? null });
|
|
687
|
+
}
|
|
688
|
+
}
|
|
689
|
+
return signals;
|
|
690
|
+
}
|
|
691
|
+
|
|
677
692
|
function spawnFindings(journalPath, at, dirName, events, reference, staleHours) {
|
|
678
693
|
const findings = [];
|
|
679
694
|
const { open } = pairSpawns(events);
|
|
695
|
+
const signals = lastSignals(events);
|
|
680
696
|
for (const agent of sortedNames(open.keys())) {
|
|
681
697
|
for (const spawn of open.get(agent)) {
|
|
682
698
|
const age = reference === null ? null : hoursBetween(spawn.ts, reference);
|
|
683
699
|
const where = `${show(spawn.data.ticket ?? 'no ticket')}, role ${show(spawn.data.role)}`;
|
|
684
|
-
|
|
700
|
+
// `lastSignals` is keyed by agent NAME, and ADR-18 permits a name to be
|
|
701
|
+
// re-spawned once its previous spawn is closed — so the latest signal
|
|
702
|
+
// under this name may belong to an incarnation that has already
|
|
703
|
+
// reported, whose blockage the report cleared. Only a signal emitted
|
|
704
|
+
// during THIS spawn describes the agent running now; a pair that cannot
|
|
705
|
+
// be ordered (a hand-edited timestamp) is not evidence either.
|
|
706
|
+
const latest = signals.get(agent) ?? null;
|
|
707
|
+
const sinceSpawn = latest === null ? null : hoursBetween(spawn.ts, latest.ts);
|
|
708
|
+
const signal = sinceSpawn !== null && sinceSpawn >= 0 ? latest : null;
|
|
709
|
+
const blockedHours =
|
|
710
|
+
signal?.state === 'blocked' && reference !== null ? hoursBetween(signal.ts, reference) : null;
|
|
711
|
+
if (blockedHours !== null && blockedHours >= DEFAULT_BLOCKED_HOURS) {
|
|
712
|
+
findings.push(
|
|
713
|
+
finding(
|
|
714
|
+
'spawn-blocked',
|
|
715
|
+
at,
|
|
716
|
+
`agent "${show(agent)}" reported itself BLOCKED ${blockedHours.toFixed(1)} h of journal time ago ` +
|
|
717
|
+
`(${show(signal.detail ?? 'no detail')}) and nothing has cleared it. ${where}`,
|
|
718
|
+
closeSpawnHint(journalPath, spawn.init ?? dirName, agent),
|
|
719
|
+
),
|
|
720
|
+
);
|
|
721
|
+
} else if (age !== null && age >= staleHours) {
|
|
685
722
|
findings.push(
|
|
686
723
|
finding(
|
|
687
724
|
'spawn-stale',
|
|
@@ -697,7 +734,9 @@ function spawnFindings(journalPath, at, dirName, events, reference, staleHours)
|
|
|
697
734
|
finding(
|
|
698
735
|
'spawn-open',
|
|
699
736
|
at,
|
|
700
|
-
`agent "${show(agent)}" is still working (spawned ${show(spawn.ts)})
|
|
737
|
+
`agent "${show(agent)}" is still working (spawned ${show(spawn.ts)})` +
|
|
738
|
+
(signal ? ` — last signal ${show(signal.state)} at ${show(signal.ts)}` : '') +
|
|
739
|
+
`. ${where}`,
|
|
701
740
|
),
|
|
702
741
|
);
|
|
703
742
|
}
|
package/scripts/journal.mjs
CHANGED
|
@@ -40,12 +40,15 @@ export const EVENT_TYPES = Object.freeze([
|
|
|
40
40
|
'init.created',
|
|
41
41
|
'plan.accepted',
|
|
42
42
|
'ticket.created',
|
|
43
|
+
'ticket.status',
|
|
43
44
|
'spawn',
|
|
44
45
|
'report',
|
|
46
|
+
'progress',
|
|
45
47
|
'gate',
|
|
46
48
|
'review',
|
|
47
49
|
'merge',
|
|
48
50
|
'decision',
|
|
51
|
+
'finding',
|
|
49
52
|
'lease.acquired',
|
|
50
53
|
'lease.released',
|
|
51
54
|
'checkpoint',
|
|
@@ -58,17 +61,20 @@ export const EVENT_TYPES = Object.freeze([
|
|
|
58
61
|
* prefix to issue it under. `ticket.created` is deliberately absent: a ticket
|
|
59
62
|
* id comes from the plan, which numbers its own stories.
|
|
60
63
|
*/
|
|
61
|
-
export const ID_ISSUED_FOR = Object.freeze(Object.assign(Object.create(null), { decision: 'D' }));
|
|
64
|
+
export const ID_ISSUED_FOR = Object.freeze(Object.assign(Object.create(null), { decision: 'D', finding: 'F' }));
|
|
62
65
|
|
|
63
66
|
/** Per-type required keys inside `data` (data may always carry extra keys). */
|
|
64
67
|
export const DATA_REQUIRED = Object.freeze({
|
|
65
68
|
'ticket.created': ['id'],
|
|
69
|
+
'ticket.status': ['ticket', 'column'],
|
|
66
70
|
spawn: ['agent', 'role'],
|
|
67
71
|
report: ['agent', 'verdict'],
|
|
72
|
+
progress: ['agent', 'state'],
|
|
68
73
|
gate: ['kind', 'result'],
|
|
69
74
|
review: ['ticket', 'verdict', 'by'],
|
|
70
75
|
merge: ['ticket', 'sha'],
|
|
71
76
|
decision: ['id', 'text'],
|
|
77
|
+
finding: ['area', 'claim'],
|
|
72
78
|
'lease.acquired': ['resource', 'holder'],
|
|
73
79
|
'lease.released': ['resource', 'holder'],
|
|
74
80
|
checkpoint: ['phase', 'next_steps'],
|
|
@@ -76,6 +82,30 @@ export const DATA_REQUIRED = Object.freeze({
|
|
|
76
82
|
error: ['class'],
|
|
77
83
|
});
|
|
78
84
|
|
|
85
|
+
/**
|
|
86
|
+
* Closed VALUE sets inside `data`, for the same reason the event set is
|
|
87
|
+
* closed: an unknown value must be a loud rejection at append time, not a
|
|
88
|
+
* surprise in a projection. Hard errors are safe here because both types are
|
|
89
|
+
* new — no legacy journal can retroactively fail `validate`.
|
|
90
|
+
*
|
|
91
|
+
* `ticket.status.column` is deliberately NARROW: only the lanes no lifecycle
|
|
92
|
+
* event can ever derive. Anything broader would be a second source of truth
|
|
93
|
+
* against the derived board (`done` is what `merge` means; an override saying
|
|
94
|
+
* so would let the two disagree).
|
|
95
|
+
*/
|
|
96
|
+
export const DATA_ENUMS = Object.freeze({
|
|
97
|
+
progress: Object.freeze({ state: Object.freeze(['started', 'working', 'blocked', 'unblocked']) }),
|
|
98
|
+
'ticket.status': Object.freeze({ column: Object.freeze(['blocked', 'waiting-operator', 'parked']) }),
|
|
99
|
+
});
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Free-text keys with a size ceiling, in codepoints. REJECTED at append,
|
|
103
|
+
* never truncated — the journal does not silently shorten anything. Long
|
|
104
|
+
* material belongs in NOTES.md with a reference here. `validateJournal`
|
|
105
|
+
* reports historical oversizes as warnings only (no retroactive errors).
|
|
106
|
+
*/
|
|
107
|
+
export const CAPPED_DATA_KEYS = Object.freeze({ detail: 2000, claim: 2000, proof: 2000 });
|
|
108
|
+
|
|
79
109
|
/**
|
|
80
110
|
* A journal-derived value on its way into a HUMAN-READABLE MESSAGE.
|
|
81
111
|
*
|
|
@@ -130,10 +160,37 @@ export function validateEvent(event) {
|
|
|
130
160
|
errors.push(`data.id must be a string for ev "${q(event.ev)}" (got ${typeof event.data.id})`);
|
|
131
161
|
}
|
|
132
162
|
}
|
|
163
|
+
const enums = DATA_ENUMS[event.ev];
|
|
164
|
+
if (enums) {
|
|
165
|
+
for (const [key, allowed] of Object.entries(enums)) {
|
|
166
|
+
if (key in event.data && !allowed.includes(event.data[key])) {
|
|
167
|
+
// Name the whole set, same as the closed event set above: the agent
|
|
168
|
+
// recovering from this error has no other source of truth.
|
|
169
|
+
errors.push(
|
|
170
|
+
`data.${q(key)} "${q(event.data[key])}" is not valid for ev "${q(event.ev)}" — valid: ${allowed.join(', ')}`,
|
|
171
|
+
);
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
133
175
|
}
|
|
134
176
|
return errors;
|
|
135
177
|
}
|
|
136
178
|
|
|
179
|
+
/**
|
|
180
|
+
* The oversize problem of one capped data key, or null. Codepoints, not
|
|
181
|
+
* UTF-16 units, same as every other length rule in this repo.
|
|
182
|
+
*/
|
|
183
|
+
export function cappedKeyProblem(data) {
|
|
184
|
+
if (data === null || typeof data !== 'object') return null;
|
|
185
|
+
for (const [key, cap] of Object.entries(CAPPED_DATA_KEYS)) {
|
|
186
|
+
const value = data[key];
|
|
187
|
+
if (typeof value === 'string' && Array.from(value).length > cap) {
|
|
188
|
+
return `data.${key} is ${Array.from(value).length} codepoints (cap ${cap}) — put the full text in NOTES.md and reference it here`;
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
return null;
|
|
192
|
+
}
|
|
193
|
+
|
|
137
194
|
// -------------------------------------------------- spawn ↔ report pairing
|
|
138
195
|
|
|
139
196
|
/**
|
|
@@ -410,7 +467,10 @@ function appendUnderLock(file, event, preread = null) {
|
|
|
410
467
|
if (errors.length > 0) {
|
|
411
468
|
throw new Error('invalid event: ' + errors.join('; '));
|
|
412
469
|
}
|
|
413
|
-
if (stamped.ev === 'spawn' || stamped.ev === 'report') {
|
|
470
|
+
if (stamped.ev === 'spawn' || stamped.ev === 'report' || stamped.ev === 'progress') {
|
|
471
|
+
// `progress` joins the guard because data.agent is how a signal attaches
|
|
472
|
+
// to the agent row in the fold — a non-canonical name would silently
|
|
473
|
+
// fail to attach rather than error anywhere.
|
|
414
474
|
const problem = agentNameProblem(stamped.data.agent);
|
|
415
475
|
if (problem) {
|
|
416
476
|
throw new Error(
|
|
@@ -419,6 +479,10 @@ function appendUnderLock(file, event, preread = null) {
|
|
|
419
479
|
);
|
|
420
480
|
}
|
|
421
481
|
}
|
|
482
|
+
{
|
|
483
|
+
const oversize = cappedKeyProblem(stamped.data);
|
|
484
|
+
if (oversize) throw new Error(`invalid event: ${oversize}`);
|
|
485
|
+
}
|
|
422
486
|
if (stamped.ev === 'spawn') {
|
|
423
487
|
// ADR-18: refuse a second OPEN spawn for one agent name. Same lock as the
|
|
424
488
|
// write, same read as the clamp — a check outside the lock would let two
|
|
@@ -556,6 +620,13 @@ export function validateJournal(file) {
|
|
|
556
620
|
for (const [raw, problem] of badNames) {
|
|
557
621
|
warnings.push(`unusable data.agent ${q(raw)}: ${problem} — excluded from spawn↔report pairing`);
|
|
558
622
|
}
|
|
623
|
+
// Historical oversizes are warnings, never errors: the cap is enforced at
|
|
624
|
+
// append time, and a hand-edited file must stay visible without turning a
|
|
625
|
+
// whole journal's `validate` red retroactively.
|
|
626
|
+
events.forEach((e, i) => {
|
|
627
|
+
const oversize = cappedKeyProblem(e?.data);
|
|
628
|
+
if (oversize) warnings.push(`event ${i + 1}: ${oversize}`);
|
|
629
|
+
});
|
|
559
630
|
return { ok: errors.length === 0, errors, warnings, count: events.length, truncatedTail };
|
|
560
631
|
}
|
|
561
632
|
|
package/scripts/project.mjs
CHANGED
|
@@ -178,6 +178,37 @@ function list(items) {
|
|
|
178
178
|
|
|
179
179
|
// ------------------------------------------------------------------ fold
|
|
180
180
|
|
|
181
|
+
/** The open blockage this agent reported clears when the agent moves on. */
|
|
182
|
+
function clearBlockageBy(state, agent) {
|
|
183
|
+
state.blockages.delete(String(agent));
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** A `review`/`merge` settles the ticket for EVERY agent blocked on it. */
|
|
187
|
+
function clearBlockagesOn(state, ticketId) {
|
|
188
|
+
for (const [key, blockage] of state.blockages) {
|
|
189
|
+
// A ticketless blockage is keyed to its agent and belongs to no ticket —
|
|
190
|
+
// the `(no ticket)` pseudo-ticket of a review/merge without `data.ticket`
|
|
191
|
+
// is a different thing and must not sweep it up.
|
|
192
|
+
if (blockage.ticket != null && String(blockage.ticket) === ticketId) state.blockages.delete(key);
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* A `report` — and a `review`, which is the reviewer's completion event —
|
|
198
|
+
* ENDS that agent's stint, so everything still keyed by its name goes with it.
|
|
199
|
+
*
|
|
200
|
+
* ADR-18 permits a later `spawn` to reuse the name once the prior one is
|
|
201
|
+
* closed, and that is the standard close-spawn recovery path, not an exotic
|
|
202
|
+
* journal. Kept, these records render against the NEXT incarnation: a fresh
|
|
203
|
+
* agent that has emitted nothing showed as `blocked at <old ts>` while
|
|
204
|
+
* `## Open blockages` said _none_ — one document contradicting itself. Cleared
|
|
205
|
+
* here, at fold time, so no reader has to compare timestamps of its own.
|
|
206
|
+
*/
|
|
207
|
+
function closeAgent(state, agent) {
|
|
208
|
+
clearBlockageBy(state, agent);
|
|
209
|
+
state.progressByAgent.delete(String(agent));
|
|
210
|
+
}
|
|
211
|
+
|
|
181
212
|
/**
|
|
182
213
|
* Fold a journal read into the projection state. Pure: no clock, no I/O.
|
|
183
214
|
* Every closed-set event type must hit a branch here; anything else is
|
|
@@ -210,6 +241,25 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
210
241
|
milestones: [],
|
|
211
242
|
unusableAgentNames: [],
|
|
212
243
|
ambiguousAgents: [],
|
|
244
|
+
// agent name -> latest self-reported signal (last one wins)
|
|
245
|
+
progressByAgent: new Map(),
|
|
246
|
+
// agent name -> that agent's open blockage, the ticket inside the value.
|
|
247
|
+
//
|
|
248
|
+
// Keyed by AGENT and not by ticket, because one agent has at most one live
|
|
249
|
+
// blockage (last-blocked-wins, exactly like its last signal) while one
|
|
250
|
+
// ticket can block SEVERAL agents. Under ticket keys the second agent's
|
|
251
|
+
// record replaced the first's, and the second agent's next movement signal
|
|
252
|
+
// then deleted a blockage its owner had never cleared — so an agent stayed
|
|
253
|
+
// stuck with nothing anywhere saying so. The ticket survives as rendered
|
|
254
|
+
// context and as what `review`/`merge` match against.
|
|
255
|
+
//
|
|
256
|
+
// Cleared by `unblocked`/`started`/`working` from the SAME agent, by that
|
|
257
|
+
// agent's report/review, and by a `review`/`merge` on the ticket — AT FOLD
|
|
258
|
+
// TIME, so no reader needs temporal reasoning of its own.
|
|
259
|
+
blockages: new Map(),
|
|
260
|
+
findings: [],
|
|
261
|
+
// `ticket.status` events naming a ticket no other event mentions
|
|
262
|
+
unknownOverrides: [],
|
|
213
263
|
};
|
|
214
264
|
|
|
215
265
|
/**
|
|
@@ -259,6 +309,7 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
259
309
|
report: null,
|
|
260
310
|
review: null,
|
|
261
311
|
merge: null,
|
|
312
|
+
override: null,
|
|
262
313
|
lastTs: seenTs ?? null,
|
|
263
314
|
});
|
|
264
315
|
}
|
|
@@ -357,8 +408,59 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
357
408
|
});
|
|
358
409
|
}
|
|
359
410
|
if (data.ticket != null) {
|
|
360
|
-
ticketOf(data.ticket, ts)
|
|
411
|
+
const t = ticketOf(data.ticket, ts);
|
|
412
|
+
t.report = { verdict: data.verdict ?? null, ts, by: data.agent ?? actor };
|
|
413
|
+
t.override = null; // a lifecycle event outranks a hand-set lane
|
|
414
|
+
}
|
|
415
|
+
if (data.agent != null) closeAgent(state, data.agent);
|
|
416
|
+
break;
|
|
417
|
+
}
|
|
418
|
+
case 'progress': {
|
|
419
|
+
const agent = String(data.agent ?? '(no agent)');
|
|
420
|
+
state.progressByAgent.set(agent, {
|
|
421
|
+
state: data.state ?? null,
|
|
422
|
+
ticket: data.ticket ?? null,
|
|
423
|
+
detail: data.detail ?? null,
|
|
424
|
+
next: data.next ?? null,
|
|
425
|
+
ts,
|
|
426
|
+
});
|
|
427
|
+
if (data.state === 'blocked') {
|
|
428
|
+
state.blockages.set(agent, { ticket: data.ticket ?? null, agent, detail: data.detail ?? null, ts });
|
|
429
|
+
} else {
|
|
430
|
+
// started / working / unblocked all say "this agent is moving";
|
|
431
|
+
// whatever it reported itself blocked on is no longer blocking.
|
|
432
|
+
clearBlockageBy(state, agent);
|
|
433
|
+
}
|
|
434
|
+
break;
|
|
435
|
+
}
|
|
436
|
+
case 'finding':
|
|
437
|
+
state.findings.push({
|
|
438
|
+
id: data.id ?? null,
|
|
439
|
+
area: data.area ?? null,
|
|
440
|
+
claim: data.claim ?? null,
|
|
441
|
+
proof: data.proof ?? null,
|
|
442
|
+
ticket: data.ticket ?? null,
|
|
443
|
+
confidence: data.confidence ?? null,
|
|
444
|
+
ts,
|
|
445
|
+
actor,
|
|
446
|
+
});
|
|
447
|
+
break;
|
|
448
|
+
case 'ticket.status': {
|
|
449
|
+
// An override is a LANE, not progress: it must never move the percent.
|
|
450
|
+
// Minting a ledger ticket for an id no other event mentions did exactly
|
|
451
|
+
// that — one mistyped id (`T-1O` for `T-10`) enlarged the denominator
|
|
452
|
+
// and dropped the headline percent, while the ticket the operator meant
|
|
453
|
+
// to park stayed unparked. So the override lands only on a ticket the
|
|
454
|
+
// journal already knows; an unknown one is refused OUT LOUD (see
|
|
455
|
+
// `warnings()`) rather than inventing the ticket it names, because a
|
|
456
|
+
// silent exclusion is the failure ADR-19 correction 1 forbids.
|
|
457
|
+
const key = String(data.ticket ?? '(no ticket)');
|
|
458
|
+
if (!state.tickets.has(key)) {
|
|
459
|
+
state.unknownOverrides.push({ ticket: key, ts });
|
|
460
|
+
break;
|
|
361
461
|
}
|
|
462
|
+
const t = ticketOf(key, ts);
|
|
463
|
+
t.override = { column: data.column ?? null, reason: data.reason ?? null, until: data.until ?? null, ts };
|
|
362
464
|
break;
|
|
363
465
|
}
|
|
364
466
|
case 'gate': {
|
|
@@ -376,20 +478,26 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
376
478
|
// `review`/`merge` require data.ticket, but a hand-written or older
|
|
377
479
|
// journal may omit it — bucket those under a visible pseudo-ticket
|
|
378
480
|
// 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
|
-
|
|
481
|
+
case 'review': {
|
|
482
|
+
const t = ticketOf(data.ticket ?? '(no ticket)', ts);
|
|
483
|
+
t.review = { verdict: data.verdict ?? null, by: data.by ?? actor, ts };
|
|
484
|
+
t.override = null;
|
|
485
|
+
clearBlockagesOn(state, t.id);
|
|
486
|
+
// The review is the REVIEWER's completion event, as a report is the
|
|
487
|
+
// implementer's: pairSpawns closes the reviewer's spawn on `data.by`,
|
|
488
|
+
// and the same correlator closes what that spawn left behind. Without
|
|
489
|
+
// it a reviewer's ticketless blockage outlived its own review with no
|
|
490
|
+
// later event that could ever clear it.
|
|
491
|
+
if (data.by != null) closeAgent(state, data.by);
|
|
385
492
|
break;
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
493
|
+
}
|
|
494
|
+
case 'merge': {
|
|
495
|
+
const t = ticketOf(data.ticket ?? '(no ticket)', ts);
|
|
496
|
+
t.merge = { sha: data.sha ?? null, mode: data.mode ?? null, ts };
|
|
497
|
+
t.override = null;
|
|
498
|
+
clearBlockagesOn(state, t.id);
|
|
392
499
|
break;
|
|
500
|
+
}
|
|
393
501
|
case 'decision':
|
|
394
502
|
state.decisions.push({ id: data.id ?? '(no id)', text: data.text ?? null, ts, actor });
|
|
395
503
|
break;
|
|
@@ -433,6 +541,10 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
433
541
|
|
|
434
542
|
/** Human-readable status of one ticket, derived from the strongest signal. */
|
|
435
543
|
export function ticketStatus(t) {
|
|
544
|
+
// A hand-set lane outranks derivation — but only until the next stronger
|
|
545
|
+
// lifecycle event, which clears it AT FOLD TIME. It never touches the
|
|
546
|
+
// merged count or the percent: an override is a lane, not progress.
|
|
547
|
+
if (t.override) return `${t.override.column ?? '(no column)'} (set by ticket.status)`;
|
|
436
548
|
if (t.merge) return `merged (${t.merge.sha ?? 'no sha'})`;
|
|
437
549
|
if (t.review) return `review: ${t.review.verdict ?? 'no verdict'}`;
|
|
438
550
|
if (t.report) return `reported: ${t.report.verdict ?? 'no verdict'}`;
|
|
@@ -477,6 +589,11 @@ export function warnings(state) {
|
|
|
477
589
|
for (const [ev, n] of sortByKey([...state.unknownTypes.entries()], (e) => e[0])) {
|
|
478
590
|
out.push(`unknown event type "${inlinePlain(ev)}" x${n} — counted but not folded (newer Tyran?)`);
|
|
479
591
|
}
|
|
592
|
+
// The lane the operator meant to set is NOT set, and the id they typed is the
|
|
593
|
+
// only thing that can tell them why.
|
|
594
|
+
for (const { ticket } of state.unknownOverrides) {
|
|
595
|
+
out.push(`ticket.status for unknown ticket "${inlinePlain(ticket)}" — ignored (an override never invents a ticket)`);
|
|
596
|
+
}
|
|
480
597
|
if (state.initiatives.length > 1) {
|
|
481
598
|
out.push(
|
|
482
599
|
`journal mixes ${state.initiatives.length} initiatives: ${state.initiatives.map((i) => inlinePlain(i)).join(', ')}`,
|
|
@@ -529,17 +646,54 @@ function renderState(state) {
|
|
|
529
646
|
parts.push('\n## Agents\n\n');
|
|
530
647
|
parts.push(
|
|
531
648
|
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
|
-
|
|
649
|
+
['Agent', 'Role', 'Model', 'Ticket', 'Worktree', 'Status', 'Spawned', 'Last signal'],
|
|
650
|
+
sortByKey(state.agents, (a) => `${a.agent} ${a.spawnTs ?? ''}`).map((a) => {
|
|
651
|
+
// A signal that outlived its report is stale by definition, and cannot
|
|
652
|
+
// be read here: the report deleted it at fold time (see `closeAgent`),
|
|
653
|
+
// and only running rows carry a signal at all. The filter alone was not
|
|
654
|
+
// enough — a re-spawned name is running again.
|
|
655
|
+
const signal = a.status === 'running' ? state.progressByAgent.get(a.agent) : null;
|
|
656
|
+
return [
|
|
657
|
+
inline(a.agent),
|
|
658
|
+
inline(a.role),
|
|
659
|
+
inline(a.model),
|
|
660
|
+
inline(a.ticket),
|
|
661
|
+
inline(a.worktree),
|
|
662
|
+
a.status === 'running'
|
|
663
|
+
? '**running (no report yet)**'
|
|
664
|
+
: `${inline(a.status)}${a.verdict == null ? '' : `: ${inline(a.verdict)}`}`,
|
|
665
|
+
inline(a.spawnTs),
|
|
666
|
+
signal ? `${inline(signal.state)} at ${inline(signal.ts)}` : inline(null),
|
|
667
|
+
];
|
|
668
|
+
}),
|
|
669
|
+
),
|
|
670
|
+
);
|
|
671
|
+
|
|
672
|
+
parts.push('\n## Open blockages\n\n');
|
|
673
|
+
parts.push(
|
|
674
|
+
table(
|
|
675
|
+
['Ticket', 'Agent', 'Detail', 'Since'],
|
|
676
|
+
sortByKey([...state.blockages.values()], (b) => `${b.ticket ?? ''} ${b.agent}`).map((b) => [
|
|
677
|
+
inline(b.ticket),
|
|
678
|
+
inline(b.agent),
|
|
679
|
+
inline(b.detail),
|
|
680
|
+
inline(b.ts),
|
|
681
|
+
]),
|
|
682
|
+
),
|
|
683
|
+
);
|
|
684
|
+
|
|
685
|
+
parts.push('\n## Findings\n\n');
|
|
686
|
+
parts.push(
|
|
687
|
+
table(
|
|
688
|
+
['Id', 'Area', 'Claim', 'Proof', 'Ticket', 'By', 'At'],
|
|
689
|
+
state.findings.map((f) => [
|
|
690
|
+
inline(f.id),
|
|
691
|
+
inline(f.area),
|
|
692
|
+
inline(f.claim),
|
|
693
|
+
inline(f.proof),
|
|
694
|
+
inline(f.ticket),
|
|
695
|
+
inline(f.actor),
|
|
696
|
+
inline(f.ts),
|
|
543
697
|
]),
|
|
544
698
|
),
|
|
545
699
|
);
|
package/skills/run/SKILL.md
CHANGED
|
@@ -164,10 +164,28 @@ open one.
|
|
|
164
164
|
list: decide and record. Without this you ask a second time for consent
|
|
165
165
|
you already have, which is the most common reason an operator ends up
|
|
166
166
|
chasing you instead of reading reports.
|
|
167
|
+
- **Operator messages mid-run queue; none is dropped silently.** Triage
|
|
168
|
+
each at the next natural pause: which initiative (or a new one), what
|
|
169
|
+
size, then a `ticket.created` carrying `id` — the one key `append` does
|
|
170
|
+
NOT issue for you, so read it from the journal and never from memory:
|
|
171
|
+
`journal.mjs next-id <abs-journal> T` returns the next one, continuing
|
|
172
|
+
the plan's numbering — plus `title`, `deps` and `files_predicted`; or a
|
|
173
|
+
`decision` when it changes course rather than adds work. Confirm in one
|
|
174
|
+
line — "queued as T-9". A thought that never reached the journal does
|
|
175
|
+
not exist. `ticket.status` is your lane override for the three states no
|
|
176
|
+
lifecycle event can derive (`blocked`, `waiting-operator`, `parked`);
|
|
177
|
+
the next report, review or merge clears it.
|
|
178
|
+
- **Scout `DURABLE:` findings, you journal** as `finding` events — the
|
|
179
|
+
required keys are `area` + `claim` (the area is the path or subsystem the
|
|
180
|
+
scout's proof points at), plus that `proof` — scouts write nothing
|
|
181
|
+
themselves. Implementers and reviewers append their own.
|
|
167
182
|
2. **Fresh context per task.** Handoffs are SELF-CONTAINED; the agent
|
|
168
183
|
disappears afterwards. Never ask the operator to compact. **Every handoff
|
|
169
184
|
carries eight things:** (1) the role and one story, one goal; (2) paths to
|
|
170
|
-
the files of record
|
|
185
|
+
the files of record — including the ABSOLUTE path of the initiative
|
|
186
|
+
journal in the MAIN checkout and the initiative slug, because worktree
|
|
187
|
+
agents append their `progress` and `finding` events there;
|
|
188
|
+
(3) the iron rules copied VERBATIM, not linked;
|
|
171
189
|
(4) the lease protocol (rule 7); (5) the **evidence contract** — the report
|
|
172
190
|
must contain raw command output (exit codes, `X passed / Y failed`); a
|
|
173
191
|
paraphrase like "tests are green" with no log is a REJECTED report. Final
|
|
@@ -252,6 +270,12 @@ open one.
|
|
|
252
270
|
(XL); product, visual and irreversible decisions, put in plain language
|
|
253
271
|
with your recommendation; anything hard to undo or visible outside the
|
|
254
272
|
repo. **"Shall I continue?" is forbidden.**
|
|
273
|
+
**Every question to the operator lands in the journal before (or as) you
|
|
274
|
+
ask it**: a `gate` event, `result: WAITING_ON_OPERATOR`, `data` carrying
|
|
275
|
+
`question`, `recommendation`, `default` and `ticket` when it has one — a
|
|
276
|
+
question that lives only in chat has to be re-litigated after every
|
|
277
|
+
compaction. When answered, append the same `kind` with `result: answered`
|
|
278
|
+
plus a `decision` recording the answer in the operator's words.
|
|
255
279
|
**Check the brake before every spawn and every merge:**
|
|
256
280
|
`node ${CLAUDE_PLUGIN_ROOT}/scripts/stop-check.mjs` — exit 1 means the
|
|
257
281
|
operator created `.tyran/STOP`. Halt, report where you got to, and do not
|