@jjanczur/tyran 0.1.38 → 0.1.39

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.
@@ -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.38",
14
+ "version": "0.1.39",
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.38",
3
+ "version": "0.1.39",
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,60 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.39 — 2026-08-17
4
+
5
+ ### A fifth agent, and the conductor plans from the board it shows you
6
+
7
+ The operator challenged all three of 0.1.38's "deliberately NOT added" calls.
8
+ Two survived the challenge with their reasons intact; one did not, and the
9
+ verifier is the result.
10
+
11
+ **`tyran:verifier`** — mechanical validation on the cheapest tier. It runs
12
+ exactly the commands it is handed, reports exit codes and counts verbatim,
13
+ compares them against the last green baseline, and never edits, fixes or
14
+ theorizes. A red suite is its product, not its failure. The routing table
15
+ already priced this mode (`bookkeeping` at cheap in every profile); nothing
16
+ ran on it. Now the conductor's merge-time validation is delegated like
17
+ everything else — a full suite bills the same tokens whoever runs it, and
18
+ running it in the conductor's context spends the plan's own memory on
19
+ watching a progress bar. The evidence gate binds it hardest of all
20
+ (`enforce`): a verifier report without raw output is a verifier that
21
+ verified nothing. A guard test pins the empty tool grant, and the prompt
22
+ owns the absence in a sentence a future "helpful" edit would have to delete.
23
+
24
+ **The conductor now plans FROM the kanban, moves tickets on it, and knows
25
+ the operator is watching the same one.** It wrote the board and never read
26
+ it: the `ready` lane IS the schedulable set (a ticket lands there only when
27
+ every dependency is merged), `blocked` and `changes-requested` are the
28
+ re-route queue, and distributing work from memory is how two agents get one
29
+ story. Moving a ticket is appending an event — the lifecycle moves the
30
+ working lanes on its own, `ticket.status` (with a reason) parks, blocks or
31
+ hands to the operator, a newer override replaces an older one, and the next
32
+ lifecycle event clears it. And there is only ONE board: the dashboard the
33
+ session autostarts runs the same fold over the same journals, so a moved
34
+ ticket is on the operator's screen within one refresh — narrating board
35
+ state in chat that the journal does not hold reads as either a stale
36
+ conductor or a broken board.
37
+
38
+ **Cards say who is on them RIGHT NOW.** The card face showed the historical
39
+ name list — "who ever touched this" — while the operator's question on a
40
+ large ticket is "who is doing what". Live agents join onto cards by
41
+ initiative AND ticket (two initiatives' T-3s never claim each other's
42
+ workers), state-coloured, with BLOCKED said out loud; the historical list
43
+ survives only when nobody is on it now, and the run-by-run record stays in
44
+ the detail panel's execution table.
45
+
46
+ The other two challenges, answered rather than deflected: no new skill —
47
+ the CI cap can indeed be raised, but the barrier was never the cap, it is
48
+ that no repeated need has graduated yet (the verifier is an agent precisely
49
+ because its protocol is its prompt); and no peer-to-peer evidence channel —
50
+ teams mode already gives peer NOTIFICATION, and evidence stays in the
51
+ journal because a teammate message dies with the session while the journal
52
+ survives compaction.
53
+
54
+ Surfaces corrected on the way: README's pitch and both agents-page tables
55
+ still carried the pre-forfeit reviewer ("no editing tools"), wrapped across
56
+ a line break where the earlier grep missed it.
57
+
3
58
  ## 0.1.38 — 2026-08-17
4
59
 
5
60
  ### The conductor is a project manager, and the prompts now argue it
package/README.md CHANGED
@@ -36,8 +36,8 @@ questions, each with his recommendation — turns the plan into tickets on a
36
36
  board, and hands each piece to a **dedicated subagent with fresh context and a
37
37
  model tier matched to how hard that piece actually is.** A good manager doesn't
38
38
  put a principal engineer on a grep: a scout reads the repo on the cheap tier,
39
- implementers take one story each on their own branch, the reviewer has no
40
- editing tools at all, and security review always gets the strongest tier — a
39
+ implementers take one story each on their own branch, the reviewer can never
40
+ bless a patch it wrote, and security review always gets the strongest tier — a
41
41
  floor no cost profile or flag can lower.
42
42
 
43
43
  That is a cost lever and a quality lever at the same time. The conductor holds
@@ -288,7 +288,7 @@ says why, and covers the lanes, the drill-down and answering a question.
288
288
 
289
289
  ## What ships
290
290
 
291
- Fourteen skills and four agents. Six of the skills are the conductor's own
291
+ Fourteen skills and five agents. Six of the skills are the conductor's own
292
292
  machinery, though commands rather than internals — `/tyran:doctor` runs on any
293
293
  repo, initiative or not — and the other eight are standalone protocols.
294
294
 
@@ -311,14 +311,15 @@ repo, initiative or not — and the other eight are standalone protocols.
311
311
 
312
312
  Agents: `tyran:scout` (recon, read-only), `tyran:implementer` (one story, own
313
313
  branch), `tyran:reviewer` (may fix what it finds, but editing forfeits
314
- `APPROVE` — it can never bless its own patch), `tyran:retro`. A skill is admitted only when something already asks
314
+ `APPROVE` — it can never bless its own patch), `tyran:verifier` (runs the
315
+ suite on the cheapest tier, reports raw counts, never fixes), `tyran:retro`. A skill is admitted only when something already asks
315
316
  for the protocol by name, and every description is loaded into every session
316
317
  whether the skill fires or not — so the combined length is capped and CI
317
318
  enforces the cap (4352 of 5000 characters). What each one assumes, when it
318
319
  fires and who invokes it, is in
319
320
  [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
320
321
  themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
321
- it: 1586 unit tests, run with `node --test "tests/**/*.test.mjs"`.
322
+ it: 1590 unit tests, run with `node --test "tests/**/*.test.mjs"`.
322
323
 
323
324
  ## Documentation
324
325
 
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: verifier
3
+ description: Mechanical validation on the cheapest tier - runs exactly the commands it is handed, reports exit codes and counts verbatim, compares them against the baseline in the handoff, and never edits, fixes or theorizes. A red suite is its product, not its failure. Spawned by the conductor at merge time, and for the serial re-run of a failure measured while other heavy phases ran.
4
+ tools: Read, Grep, Glob, Bash
5
+ ---
6
+
7
+ You are the verifier. You run the checks; you do not fix, diagnose or improve
8
+ anything. You exist because a full suite bills the same tokens whoever runs
9
+ it — and running it inside an implementer's or the conductor's context spends
10
+ an expensive tier on watching a progress bar.
11
+
12
+ **Reply in the language the conductor writes to you in. Anything written to
13
+ disk is in English — though you should not be writing anything to disk.**
14
+
15
+ 1. **Run EXACTLY the commands the handoff names, in order.** No substitutes,
16
+ no added flags, no "while I'm here". A command that does not exist in the
17
+ repo is a finding to report, never a thing to install.
18
+ - Take the heavy-slot lease first when the handoff names one — a test
19
+ suite is a heavy phase — and release it when you finish, including when
20
+ you finish by failing.
21
+ 2. **Capture, never narrate.** For each command: the exit code and the
22
+ counter lines (`X passed / Y failed`), verbatim. For a failure, the raw
23
+ failing output — head and tail when it is huge, saying what you cut.
24
+ Nothing in your report is an adjective.
25
+ 3. **Compare against the baseline in the handoff** — the last green counts.
26
+ A new failure names the test and the command, nothing more. You do not
27
+ theorize about causes; the conductor routes that to a tier bought for it,
28
+ carrying your numbers.
29
+ 4. **One permitted re-run.** When a failure smells like the machine — a
30
+ timeout, and the handoff says other heavy phases were running at the time
31
+ — re-run that one command ONCE, serially, and report both results,
32
+ labelled. Anything beyond the single re-run is diagnosis, which is not
33
+ yours to do.
34
+ 5. **A red suite is your product, not your failure.** Report it plainly and
35
+ end. Never edit a file, never retry with modifications, never run a `git`
36
+ command that writes. You have no editing tools, and the absence is the
37
+ design: a verifier that can fix what it finds stops being a measurement.
38
+
39
+ Report: one line per command — command · exit code · counts · delta against
40
+ the baseline — then the raw output of every failure. Nothing else.
@@ -216,6 +216,10 @@ export const ROLE_BY_NAME = Object.freeze(
216
216
  reviewer: 'enforce',
217
217
  scout: 'exempt',
218
218
  retro: 'exempt',
219
+ // The verifier's entire product IS raw command output, so the evidence
220
+ // contract binds it hardest of all: a verifier report without output is
221
+ // a verifier that verified nothing.
222
+ verifier: 'enforce',
219
223
  }),
220
224
  );
221
225
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.38",
3
+ "version": "0.1.39",
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": {
@@ -850,7 +850,21 @@ if (data.schema !== 1) {
850
850
  // The badge is the whole point of the baseline: it puts what moved in
851
851
  // front of you instead of asking you to compare ten lanes by eye.
852
852
  if (moved[(c.init || '') + '/' + c.id]) button.appendChild(el('span', 'movedtag', 'moved'));
853
- if (c.agents && c.agents.length) button.appendChild(el('span', 'note', 'agents: ' + c.agents.join(', ')));
853
+ // WHO is on it RIGHT NOW — the join the operator reads a kanban for.
854
+ // On a large ticket the historical name list answers "who ever touched
855
+ // this", not "who is doing what": live agents come from the same strip
856
+ // the Overview renders, matched by initiative AND ticket so two
857
+ // initiatives' T-3s never claim each other's workers. The historical
858
+ // list stays only when nobody is on it now; the full run-by-run record
859
+ // is the detail panel's execution table.
860
+ var live = (data.agents || []).filter(function (ag) { return ag.ticket === c.id && (ag.init || '') === (c.init || ''); });
861
+ live.forEach(function (ag) {
862
+ var liveCls = ag.state === 'blocked' ? 'note age-dead' : ag.stale ? 'note age-warm' : 'note';
863
+ button.appendChild(el('span', liveCls,
864
+ 'now: ' + ag.agent + ' (' + (ag.role || 'no role') + ')' +
865
+ (ag.state === 'blocked' ? ' — BLOCKED' : ag.stale ? ' — stale' : '')));
866
+ });
867
+ if (!live.length && c.agents && c.agents.length) button.appendChild(el('span', 'note', 'agents: ' + c.agents.join(', ')));
854
868
  if (c.annotation) button.appendChild(el('span', 'note', c.annotation));
855
869
  // How long this card has stood still, on the lanes where standing still
856
870
  // IS the defect. The board would tell you an agent had been quiet for
@@ -35,6 +35,7 @@ import {
35
35
  import { basename, dirname, join, resolve } from 'node:path';
36
36
  import { fileURLToPath } from 'node:url';
37
37
  import { escapeInvisible, invisibleProblem, jsonEscapeInvisible, whitespaceProblem } from './invisible.mjs';
38
+ import { wantsHelp } from './cli-args.mjs';
38
39
 
39
40
  /** Closed set of event types. Extending it is a reviewed core change. */
40
41
  export const EVENT_TYPES = Object.freeze([
@@ -1032,6 +1033,56 @@ const CMD_FLAGS = {
1032
1033
  ask: ['actor', 'ticket', 'question', 'recommendation', 'default'],
1033
1034
  };
1034
1035
 
1036
+ /**
1037
+ * The usage text, in one place, for BOTH the answer to `--help` and the refusal
1038
+ * of a bad invocation.
1039
+ *
1040
+ * It lived inside the `UsageError` handler until 0.1.38, which meant `--help`
1041
+ * could only reach it by being a mistake: stderr, exit 2. An array joined once
1042
+ * is the shape `mistakes.mjs` already uses, and the reason it is worth copying
1043
+ * here is the table below — appended as a spread rather than as the tail of a
1044
+ * `+` chain, which is where a mechanical extraction of the old form broke.
1045
+ */
1046
+ export const JOURNAL_USAGE = [
1047
+ 'usage: journal.mjs append <file> <ev> <init> [--actor A] [--data JSON]',
1048
+ ' journal.mjs query <file> [--ev E] [--init I] [--ticket T] [--limit N]',
1049
+ ' journal.mjs validate <file> · next-id <file> <prefix> · tail <file>',
1050
+ ' journal.mjs open-spawns <file>',
1051
+ ' journal.mjs close-spawn <file> <init> <agent> --reason R [--verdict V] [--actor A]',
1052
+ ' journal.mjs ask <file> <init> --question Q [--recommendation R] [--default D] [--ticket T] [--actor A]',
1053
+ '',
1054
+ // The `--data` contract varies per event and lived only in a table no
1055
+ // command printed. A field run discovered it by rejection, one failed
1056
+ // invocation at a time.
1057
+ 'events, and the `--data` keys each one requires:',
1058
+ ...EVENT_TYPES.map((ev) => {
1059
+ const required = DATA_REQUIRED[ev];
1060
+ const issued = ID_ISSUED_FOR[ev] !== undefined ? ' (id is issued if omitted)' : '';
1061
+ return ` ${ev.padEnd(16)}${required === undefined ? '—' : required.join(', ')}${issued}`;
1062
+ }),
1063
+ ].join('\n');
1064
+
1065
+ /**
1066
+ * Whether this invocation is asking to be TOLD rather than obeyed.
1067
+ *
1068
+ * Deliberately narrower than `wantsHelp(process.argv.slice(2))`, which is what
1069
+ * the other subcommand-style commands pass. `HELP_FLAGS` includes the bare word
1070
+ * `help`, and here `help` is a legal VALUE: `next-id <file> help` issues ids
1071
+ * under the prefix "help", `--question help` is a question, `--actor help` is
1072
+ * an actor. Scanning every argument would turn each of those into a usage dump
1073
+ * under exit 0 — a command that prints something reasonable and does nothing,
1074
+ * which is the failure the symlink guard above already cost this file once.
1075
+ *
1076
+ * So: every spelling in the VERB position, and the flag spellings anywhere a
1077
+ * flag can appear — flag-shaped tokens only, and only before a bare `--`, the
1078
+ * end-of-options marker `parseFlags` already honours.
1079
+ */
1080
+ function helpRequested(cmd, args) {
1081
+ const end = args.indexOf('--');
1082
+ const flagsOnly = (end === -1 ? args : args.slice(0, end)).filter((arg) => arg.startsWith('-'));
1083
+ return wantsHelp([cmd ?? '']) || wantsHelp(flagsOnly);
1084
+ }
1085
+
1035
1086
  /**
1036
1087
  * The ONE way this CLI writes a value to a terminal.
1037
1088
  *
@@ -1060,6 +1111,13 @@ function emit(value, indent) {
1060
1111
 
1061
1112
  function main() {
1062
1113
  const [cmd, ...args] = process.argv.slice(2);
1114
+ // Before the dispatch: `--help` is not a key of CMD_FLAGS, so answering it
1115
+ // below would mean answering it as an unknown VERB — usage on stderr under
1116
+ // exit 2, help reported as a mistake.
1117
+ if (helpRequested(cmd, args)) {
1118
+ console.log(JOURNAL_USAGE);
1119
+ return;
1120
+ }
1063
1121
  try {
1064
1122
  if (!(cmd in CMD_FLAGS)) throw new UsageError();
1065
1123
  const { flags, rest } = parseFlags(args, CMD_FLAGS[cmd]);
@@ -1145,24 +1203,7 @@ function main() {
1145
1203
  }
1146
1204
  } catch (err) {
1147
1205
  if (err instanceof UsageError) {
1148
- console.error(
1149
- 'usage: journal.mjs append <file> <ev> <init> [--actor A] [--data JSON]\n' +
1150
- ' journal.mjs query <file> [--ev E] [--init I] [--ticket T] [--limit N]\n' +
1151
- ' journal.mjs validate <file> · next-id <file> <prefix> · tail <file>\n' +
1152
- ' journal.mjs open-spawns <file>\n' +
1153
- ' journal.mjs close-spawn <file> <init> <agent> --reason R [--verdict V] [--actor A]\n' +
1154
- ' journal.mjs ask <file> <init> --question Q [--recommendation R] [--default D] [--ticket T] [--actor A]\n' +
1155
- '\n' +
1156
- // The `--data` contract varies per event and lived only in a table no
1157
- // command printed. A field run discovered it by rejection, one failed
1158
- // invocation at a time.
1159
- 'events, and the `--data` keys each one requires:\n' +
1160
- EVENT_TYPES.map((ev) => {
1161
- const required = DATA_REQUIRED[ev];
1162
- const issued = ID_ISSUED_FOR[ev] !== undefined ? ' (id is issued if omitted)' : '';
1163
- return ` ${ev.padEnd(16)}${required === undefined ? '—' : required.join(', ')}${issued}`;
1164
- }).join('\n'),
1165
- );
1206
+ console.error(JOURNAL_USAGE);
1166
1207
  process.exit(2);
1167
1208
  }
1168
1209
  console.error(`journal: ${err.message}`);
package/scripts/tiers.mjs CHANGED
@@ -114,6 +114,13 @@ export const ROLE_TIERS = Object.freeze({
114
114
  // cost surfaces later as work done slightly wrong, everywhere, quietly.
115
115
  authoring: { eco: 'top', balanced: 'top', full: 'top' },
116
116
  bookkeeping: { eco: 'cheap', balanced: 'cheap', full: 'cheap' },
117
+ // Mechanical validation: run the named commands, report counts and exit
118
+ // codes, compare against a baseline. Cheap at EVERY profile because model
119
+ // strength does not change what `node --test` prints — the same claim the
120
+ // scout row makes about reading files. There is deliberately no floor and
121
+ // no escalation: a red suite is the verifier SUCCEEDING, so `--journal
122
+ // --ticket` attempt-counting must never be pointed at this role.
123
+ verifier: { eco: 'cheap', balanced: 'cheap', full: 'cheap' },
117
124
  // ADVISORY. The conductor is the operator's own session, and no plugin can
118
125
  // change a running session's model — so this row records the choice in the
119
126
  // one file where model names may live and the CLI says out loud, on stderr,
@@ -11,7 +11,8 @@ description: Conduct a task end to end, from a one-line fix to a multi-day progr
11
11
 
12
12
  You are the CONDUCTOR — a project manager, not a pair of hands. You plan,
13
13
  delegate to agents with fresh context (`tyran:scout`, `tyran:implementer`,
14
- `tyran:reviewer`, `tyran:retro`), read their reports, spot-check, merge, and
14
+ `tyran:reviewer`, `tyran:verifier`, `tyran:retro`), read their reports,
15
+ spot-check, merge, and
15
16
  hold the line on quality. The reason is arithmetic, not etiquette: your
16
17
  context is the one place the WHOLE plan lives, and it is the most expensive
17
18
  store in the system — measured once on Tyran's own development (the run its
@@ -176,6 +177,42 @@ open one.
176
177
  `board.json` are part of the set — and the cross-initiative board with
177
178
  `scripts/board.mjs`; every one of them is GENERATED — never hand-edit.
178
179
  Moving a ticket on the board IS appending an event; there is no other way.
180
+ - **Plan FROM the board, not from memory.** The kanban you regenerate is
181
+ your own planning surface, not only the operator's window: regenerate it
182
+ after every report, merge and ask — not merely at merges — and READ it
183
+ before every spawn. The `ready` lane IS the schedulable set (`boardOf`
184
+ puts a ticket there only when every dependency is merged; an unknown dep
185
+ counts unmet), so the next spawn comes from `ready` up to the hardware
186
+ ceiling — never from your recollection of what should be next.
187
+ `blocked` and `changes-requested` are your re-route queue (the
188
+ escalation rule below), `waiting-operator` is what the human owes and
189
+ must never silently gate a schedulable ticket, and a ticket you believe
190
+ is ready that the board disagrees about means the JOURNAL is missing an
191
+ event — fix the journal, never your reading of the board. Distributing
192
+ work from memory is how two agents get one story and a dependency ships
193
+ unmet; the lead's memory is the least reliable store in the system, and
194
+ the board exists so it never has to be used.
195
+ And MOVE tickets whenever the plan changes — moving is appending, so a
196
+ re-plan is one event per ticket, journalled and visible to everyone at
197
+ once. The lifecycle moves the working lanes for you (a spawn is
198
+ in-progress, a verdict and a merge move it on, `ready` appears the
199
+ moment the last dependency merges); `ticket.status` — `--data
200
+ '{"ticket":"T-n","column":"parked","reason":"..."}'` — is your free
201
+ re-arrangement for the three lanes no lifecycle event can derive
202
+ (`blocked`, `waiting-operator`, `parked`), always with the `reason` on
203
+ the event; a newer override replaces an older one, the next report,
204
+ review or merge on that ticket clears it, and one naming an unknown
205
+ ticket is refused out loud rather than inventing what it names. Park
206
+ freely and re-sequence mid-initiative without ceremony: the board after
207
+ the append IS the new plan, and a re-plan that lives only in your head
208
+ is invisible to the operator, the agents and the next session alike.
209
+ There is only ONE board, and the operator is already watching it: the
210
+ dashboard the session autostarts runs the same `boardOf` fold over the
211
+ same journals and re-renders on every refresh, so a ticket you move is
212
+ on their screen within one refresh, in the same lanes you plan from.
213
+ Never describe board state in chat that the journal does not hold — the
214
+ operator can see the real one, and a narration that disagrees with it
215
+ reads as either a stale conductor or a broken board.
179
216
  Authored, alongside the journal:
180
217
  `PLAN.md` (decomposition plus the **manifest of
181
218
  shared zones**) and `NOTES.md` (side observations, defaults you adopted,
@@ -261,12 +298,23 @@ open one.
261
298
  carries an explicit **"NO INDEPENDENT REVIEW"** stamp; staying quiet about
262
299
  it is forbidden. Tests for every non-trivial change. Repo validation per
263
300
  the project configuration. You merge, sequentially.
301
+ - **Merge-time validation is delegated too.** Spawn `tyran:verifier` — the
302
+ routing table prices it at the cheap tier in every profile — with the
303
+ exact validation commands and the last green counts; it returns exit
304
+ codes, counters and the delta, and it never fixes or theorizes. Running
305
+ the full suite in your own context is the M-sized mistake in miniature:
306
+ the same tokens, spent watching a progress bar. Its red is a FACT you
307
+ route onward, not a failure of the verifier — never point the
308
+ attempt-counting escalation at it. (Implementers and reviewers still run
309
+ their own validation; the verifier is your independent check, not their
310
+ substitute.)
264
311
  - **A `Test timed out` measured while another heavy phase was running is
265
312
  not evidence of a defect.** Re-run it serially, report the serial result,
266
313
  and say the first run was concurrent. The hardware ceiling bounds AGENT
267
314
  count, not concurrent heavy phases, so an agent can respect it and still
268
315
  produce a red only the machine caused — five such failures in one session,
269
- all green on a serial re-run.
316
+ all green on a serial re-run. That serial re-run is verifier work by
317
+ nature: one command, one baseline, no judgment.
270
318
  - **An agent that dies on a terminal API error is RESUMED, not respawned.**
271
319
  Its context, its corrected premises and its uncommitted diff all survive
272
320
  the death; a fresh agent on the same handoff redoes work already on disk.