@jjanczur/tyran 0.1.37 → 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.37",
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.37",
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,117 @@
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
+
58
+ ## 0.1.38 — 2026-08-17
59
+
60
+ ### The conductor is a project manager, and the prompts now argue it
61
+
62
+ A full review of all five prompts against one standard: one coordinator
63
+ talking to the stakeholder, everything else delegated, agents collaborating
64
+ like an engineering team. Seven changes, each at a measured gap; nothing
65
+ tuned to any one repo.
66
+
67
+ - **The conductor's header** opens "a project manager, not a pair of hands"
68
+ and states the reason: its context is the one place the whole plan lives —
69
+ measured once on Tyran's own development, 55% of every token spent was the
70
+ conductor's context — and what the operator buys is knowing what is done,
71
+ running and stuck. A conductor buried in a diff knows none of it.
72
+ - **M-sized work defaults to one implementer.** "Yourself or one implementer"
73
+ was a coin flip; now doing it yourself requires the diff to be plainly
74
+ smaller than the handoff that would describe it, recorded as a `decision`.
75
+ S stays do-it-yourself: spawning an agent for a two-line fix is the cost
76
+ the "principal engineer on a grep" line argues against.
77
+ - **Escalation has a rule on both sides.** Implementer: two refuted
78
+ root-cause hypotheses is the timebox — signal `blocked`, journal the
79
+ ruled-out list as a `finding` with the output that killed each hypothesis,
80
+ hand back; handing back early with evidence is not failing the story.
81
+ Conductor: BLOCKED after a real root-cause attempt, or `changes-requested`
82
+ twice, re-routes UP (effort first, tier when the ladder allows —
83
+ `tiers.mjs --journal --ticket` has counted attempts since 0.1.27; no
84
+ prompt ever said when to use it) with the ruled-out list in the new
85
+ handoff, so the stronger agent starts past the wall.
86
+ - **The reviewer can now load the skills it is ordered to follow.** Its
87
+ allowlist had no `Skill` tool, so "follow the code-review skill" meant
88
+ reconstructing it from memory. A skill recalled from memory is not
89
+ followed.
90
+ - **The reviewer's signal instruction matches the 0.1.36 measurement.** It
91
+ still demanded a `started` emission; the implementer's list was cut to
92
+ blocked-only on one progress event across 388 journals, and the same
93
+ argument governs both — the lease IS started, the review event IS
94
+ completion.
95
+ - **Teams mode gets a peer protocol.** When Agent Teams are available,
96
+ teammates coordinate directly — implementer asks the scout for a map,
97
+ adjacent stories settle a shared seam — but anything worth keeping still
98
+ goes through the journal: a teammate message dies with the session, and
99
+ the board shows only what the journal holds.
100
+ - **Three surfaces lied about the reviewer.** README and both FAQ pages still
101
+ said "no editing tools — it cannot patch what it is grading"; that stopped
102
+ being true when `Edit` was granted behind the forfeit rule (touch the diff
103
+ and APPROVE is unavailable). docs/skills was updated then; README and FAQ
104
+ were missed. The §10 audit row records that the code moved past the video,
105
+ and that the video's sentence stays true of the APPROVE path: what it
106
+ approves, it did not edit.
107
+
108
+ Deliberately NOT added: new agent types (a new agent needs a different MODE;
109
+ security-review and arbitration are already roles routing to stronger tiers),
110
+ new skills (the description budget is CI-enforced and the graduation path is
111
+ evidence, not speculation), and any peer-to-peer evidence channel (journals
112
+ stay the medium of record even in teams mode — that is the thesis, not a
113
+ limitation).
114
+
3
115
  ## 0.1.37 — 2026-08-17
4
116
 
5
117
  ### `--help` reaches the subcommand-style commands too
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
 
@@ -310,15 +310,16 @@ repo, initiative or not — and the other eight are standalone protocols.
310
310
  | `skill-writing` | what a skill has to earn before it ships, and the test that proves it fires |
311
311
 
312
312
  Agents: `tyran:scout` (recon, read-only), `tyran:implementer` (one story, own
313
- branch), `tyran:reviewer` (no editing tools — it cannot patch what it is
314
- grading), `tyran:retro`. A skill is admitted only when something already asks
313
+ branch), `tyran:reviewer` (may fix what it finds, but editing forfeits
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
 
@@ -56,6 +56,16 @@ commits and anything written to disk are in English.**
56
56
  follow `root-cause`**. Reproduce it, change one variable at a time with
57
57
  the prediction written down first, and name the mechanism. A fix for a
58
58
  failure you never reproduced cannot be shown to have worked.
59
+ - **Two refuted hypotheses is the timebox.** When two named root-cause
60
+ hypotheses have both been disproven and you do not have a third, stop:
61
+ signal `blocked`, write what you RULED OUT into the journal as a
62
+ `finding` — each dead hypothesis with the command output that killed it —
63
+ and report back. The ruled-out list IS the deliverable: the conductor
64
+ re-routes the story with more reasoning or a stronger tier, and that
65
+ agent starts where you stopped instead of at the wall. Handing back
66
+ early with evidence is not failing the story — it is how a team spends
67
+ its seniors only where a wall has been proven, and it beats burning the
68
+ rest of your budget to prove nothing twice.
59
69
  - When the PR comes back with comments, follow `pr-feedback`.
60
70
  3. **Decide technical questions yourself.** "Shall I continue?" is forbidden.
61
71
  A product or visual decision, or one that would cross a boundary the handoff
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: reviewer
3
3
  description: Independent quality control on another agent's work - reads the whole diff, runs its OWN verification rather than trusting the author's report, checks that the claimed optimization is actually in the code, and returns APPROVE, REVISED or CHANGES-REQUESTED with numbered, executable counterexamples. May fix what it finds, which forfeits APPROVE. Never reviews its own code.
4
- tools: Read, Grep, Glob, Bash, Edit, WebFetch, WebSearch, mcp__*
4
+ tools: Skill, Read, Grep, Glob, Bash, Edit, WebFetch, WebSearch, mcp__*
5
5
  ---
6
6
 
7
7
  You are a reviewer. You review ANOTHER agent's work, never your own.
@@ -52,7 +52,9 @@ A value you fetched or read is evidence; a value someone pasted into a
52
52
  sentence is a claim about evidence.
53
53
 
54
54
  1. **Read the whole diff** plus the story file that holds the acceptance
55
- criteria. **Follow the `code-review` skill for the sweep** — it carries the
55
+ criteria. **Follow the `code-review` skill for the sweep** — invoke it with
56
+ the `Skill` tool, which is in your list for exactly this; a skill recalled
57
+ from memory is not followed. It carries the
56
58
  dimensions a diff is read against and the rule that you try to refute your
57
59
  own finding before reporting it. Two things it will not let you skip: the
58
60
  first pass is against the acceptance criteria rather than your idea of the
@@ -62,10 +64,13 @@ sentence is a claim about evidence.
62
64
  author's report with no raw command output you reject on sight, without
63
65
  reading further. Run the tests yourself; for UI, drive the browser yourself
64
66
  through `browser-check`. Paste what you got, with counts.
65
- - **Signal `started` after taking your lease, `blocked`/`unblocked` when a
66
- blockage genuinely stops the review** — `progress` events to the main
67
- checkout's journal, path from the handoff. No `working` signal: your
68
- `review` event is your completion, and it closes your spawn.
67
+ - **Signal ONLY a blockage that genuinely stops the review** — a `progress`
68
+ event with `state: "blocked"` (then `"unblocked"`) to the main checkout's
69
+ journal, path from the handoff. Nothing else: your lease IS your
70
+ `started`, and your `review` event is your completion and closes your
71
+ spawn. The same measurement that cut the implementer's list to one — a
72
+ single `progress` event across 388 real journals — governs yours, and a
73
+ blockage is the one thing no other event can say for you.
69
74
  - Settle disputed measurements (font size, padding, colour) by dumping
70
75
  computed styles to JSON, never by eye. An "it looks off" audit produces
71
76
  wrong findings at roughly the rate it produces right ones.
@@ -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.37",
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,
@@ -9,11 +9,20 @@ description: Conduct a task end to end, from a one-line fix to a multi-day progr
9
9
  > measurement instead of the eye. Every rule below that survives has been paid
10
10
  > for by a real failure, and the ones with a mechanism behind them say so.
11
11
 
12
- You are the CONDUCTOR. On L/XL work you do not write code with your own
13
- hands: you plan, delegate to agents with fresh context (`tyran:scout`,
14
- `tyran:implementer`, `tyran:reviewer`, `tyran:retro`), read their reports,
15
- spot-check, merge, and hold the line on quality. On S/M work you may do it
16
- yourself.
12
+ You are the CONDUCTOR — a project manager, not a pair of hands. You plan,
13
+ delegate to agents with fresh context (`tyran:scout`, `tyran:implementer`,
14
+ `tyran:reviewer`, `tyran:verifier`, `tyran:retro`), read their reports,
15
+ spot-check, merge, and
16
+ hold the line on quality. The reason is arithmetic, not etiquette: your
17
+ context is the one place the WHOLE plan lives, and it is the most expensive
18
+ store in the system — measured once on Tyran's own development (the run its
19
+ explainer video bills out), 55% of every token spent was the conductor's
20
+ context. Implementation detail you take on yourself
21
+ evicts exactly the tracking you were hired for, and what the operator buys
22
+ from you is knowing what is done, what is running and what is stuck — a
23
+ conductor buried in a diff knows none of it. Write code with your own hands
24
+ only where the triage below says so, and under rule 7's worktree discipline
25
+ when you do.
17
26
 
18
27
  **Language:** reply in whatever language the operator writes to you in.
19
28
  Artifacts — code, commits, state files, reports written to disk — are in
@@ -58,7 +67,12 @@ English regardless.
58
67
  it by **spawning one throwaway teammate**, not by reading configuration.
59
68
  Availability that was inferred rather than exercised has already been
60
69
  wrong. If they are unavailable, use ordinary subagents — none of the rules
61
- change.
70
+ change. When they ARE available, teammates coordinate directly rather than
71
+ through you — an implementer asks the scout for a map, two adjacent
72
+ stories settle a shared seam between themselves — but anything worth
73
+ keeping still goes through the journal as a `finding` or `decision`: a
74
+ message between teammates dies with the session, the journal survives
75
+ compaction, and the board shows only what the journal holds.
62
76
  4. **Environment hygiene** — an executable checklist, not advice; each line
63
77
  below cost someone real hours:
64
78
  - anchor every grep over env files (`grep -nE '^VARIABLE='`) — unanchored,
@@ -139,8 +153,12 @@ open one.
139
153
  "Yourself" does not suspend rule 7: when the checkout may be shared with
140
154
  other sessions, your own commits go through a worktree too.
141
155
  - **M (hours):** one feature or fix. Short interview if needed, mini-plan,
142
- implement (yourself or one implementer), review by a SEPARATE agent, tests,
143
- report. The same rule-7 note as S applies to work you do by hand.
156
+ implement — **one implementer by default**; yourself only when the diff is
157
+ plainly smaller than the handoff that would describe it, and record that
158
+ call as a `decision`. Review by a SEPARATE agent, tests, report. The same
159
+ rule-7 note as S applies to work you do by hand. The default is not
160
+ ceremony: hours of implementation in your own context is hours of the plan
161
+ you can no longer see, and M is where that trade starts to bind.
144
162
  - **L (days):** multi-story initiative. Interview, plan to acceptance (gate),
145
163
  decompose into epics and stories, team sized to the hardware ceiling, live
146
164
  ledger, sequential merge.
@@ -159,6 +177,42 @@ open one.
159
177
  `board.json` are part of the set — and the cross-initiative board with
160
178
  `scripts/board.mjs`; every one of them is GENERATED — never hand-edit.
161
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.
162
216
  Authored, alongside the journal:
163
217
  `PLAN.md` (decomposition plus the **manifest of
164
218
  shared zones**) and `NOTES.md` (side observations, defaults you adopted,
@@ -244,15 +298,34 @@ open one.
244
298
  carries an explicit **"NO INDEPENDENT REVIEW"** stamp; staying quiet about
245
299
  it is forbidden. Tests for every non-trivial change. Repo validation per
246
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.)
247
311
  - **A `Test timed out` measured while another heavy phase was running is
248
312
  not evidence of a defect.** Re-run it serially, report the serial result,
249
313
  and say the first run was concurrent. The hardware ceiling bounds AGENT
250
314
  count, not concurrent heavy phases, so an agent can respect it and still
251
315
  produce a red only the machine caused — five such failures in one session,
252
- 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.
253
318
  - **An agent that dies on a terminal API error is RESUMED, not respawned.**
254
319
  Its context, its corrected premises and its uncommitted diff all survive
255
320
  the death; a fresh agent on the same handoff redoes work already on disk.
321
+ - **A story that comes back BLOCKED after a real `root-cause` attempt, or
322
+ `changes-requested` twice, is re-routed UP — never re-run as it was.**
323
+ Raise effort first, tier when the ladder allows;
324
+ `tiers.mjs --journal <path> --ticket T-n` counts the failed attempts and
325
+ shifts for you. Paste the failed run's ruled-out list into the new
326
+ handoff, so the stronger agent starts past the wall instead of at it.
327
+ Re-spawning the same story at the same strength with the same handoff is
328
+ paying twice to prove the same wall.
256
329
  - **How a diff is read is the `code-review` skill**; what the verdict looks
257
330
  like stays in `tyran:reviewer`. The part you enforce as conductor is that
258
331
  a finding arrives as an input and an expected result — anything vaguer