@jjanczur/tyran 0.1.27 → 0.1.29

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.27",
14
+ "version": "0.1.29",
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.27",
3
+ "version": "0.1.29",
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,142 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.29 — 2026-08-16
4
+
5
+ Tyran has videos. Five cuts, and a page that says which one to send.
6
+
7
+ ### The slate
8
+
9
+ A 3:20 explainer, a 3:53 first-session tutorial, and three vertical shorts —
10
+ the mistake, the board, the retrospective. Built with Hyperframes (HTML in,
11
+ deterministic MP4 out) and a Gemini voiceover, with burned-in captions and an
12
+ `.srt` sidecar each.
13
+
14
+ They are not five lengths of one video, which is the point of
15
+ [`docs/videos.md`](docs/videos.md): each answers a different question, and the
16
+ shorts and the tutorial fail at each other's jobs. The explainer argues, the
17
+ tutorial instructs, the board short shows rather than argues, and the retro
18
+ short is the only one whose subject is restraint.
19
+
20
+ ### The written surfaces now say what the video says
21
+
22
+ The README and the landing hero were accurate and abstract where the explainer
23
+ is concrete. Both now open on the same sentence it does — your most expensive
24
+ model renaming a variable in the same chat it judged an authentication
25
+ boundary — and carry the manager framing through to the board, the bill and the
26
+ retro. Two descriptions of one product drifting apart is the defect this repo
27
+ calls ADR-21, and the video is now the widest-reach description of Tyran, so it
28
+ is the one the prose should agree with.
29
+
30
+ ### The claims in the explainer, checked against the code
31
+
32
+ Every spoken claim was audited (`NOTES-REQUESTS.md` §10). Nine are exact, and
33
+ several turn out to be near-verbatim quotes of the mechanism's own
34
+ documentation: the four-question interview batch, the reviewer that ships with
35
+ no editing tools, the role floor applied after both the risk shift and the
36
+ override, and the three-to-knowledge / five-to-law ladder.
37
+
38
+ Two are not, and are recorded rather than quietly left:
39
+
40
+ - **"cheap tier, read only"** — the scout is granted `Bash`. *"You change
41
+ nothing"* is the first line of its instructions, which is the one form of
42
+ guarantee this project refuses to accept anywhere else. The fix is a
43
+ read-only agent class in the policy gate, not a rewording.
44
+ - **"this is not an estimate, it is the bill"** — the figures are exactly what
45
+ the sandbox board shows (404 requests, 4.53M tokens, 54.9% conductor) and the
46
+ rollup computing them is the real one, but the usage feeding it is authored,
47
+ and the board honestly labels those models `sample-large` / `sample-small`.
48
+ Publishing a real `cost.json` into the sandbox makes the line true and makes
49
+ the sandbox a better artefact than the video.
50
+
51
+ ### What is in the repository, and what is not
52
+
53
+ The video *sources* are tracked — compositions, the voiceover pipeline, the
54
+ scripts, the storyboards — because they are text and they are how a cut gets
55
+ rebuilt. The renders are not. They come to roughly 430 MB, and this repository
56
+ is what `/plugin marketplace add jjanczur/tyran` clones, so committing them
57
+ would put marketing video into every install of the plugin. Git LFS was
58
+ considered and rejected on the same ground: a clone without `git-lfs` gets
59
+ pointer files, which breaks both the Pages build and the install.
60
+
61
+ `assets/video/` carries 1.1 MB of poster frames and caption sidecars, which is
62
+ everything the README and the docs page actually reference. The cuts live on
63
+ YouTube, and their IDs live in exactly one file,
64
+ `site/src/data/videos.json`.
65
+
66
+ Tyran's own secrets gate refused the first attempt at that commit — the payload
67
+ was past the 4 MiB it can scan inside its budget, and it refuses rather than
68
+ scanning a prefix, because a partial scan that reports nothing looks exactly
69
+ like a clean one. That is the gate behaving as designed, and it is what forced
70
+ the question of which bytes really needed to be in the tree. Two MP4s turned
71
+ out to be referenced by nothing.
72
+
73
+ ## 0.1.28 — 2026-08-15
74
+
75
+ A maintenance release: the documentation site's dependencies, and three
76
+ numbers in the prose that had gone stale because nothing was watching them.
77
+
78
+ ### Five vulnerabilities, now zero
79
+
80
+ `npm audit` in `site/` reported five, three of them high, all transitive:
81
+ nanoid's infinite loop on a zero size, js-yaml, fast-uri, dompurify, and
82
+ mermaid's prototype pollution. `npm update` and `npm audit fix` clear all five
83
+ and carry astro 7.1.4 to 7.2.2, starlight 0.41.4 to 0.41.7 and playwright
84
+ 1.62.0 to 1.62.1. Lockfile only — no range in `package.json` moved, and the
85
+ plugin itself still has zero runtime dependencies, which is the property that
86
+ keeps this whole section confined to `site/`.
87
+
88
+ Verified against the built site rather than asserted: `astro check` reports 0
89
+ errors over 27 files, the build produces 18 pages, 488 of 488 root-absolute
90
+ URLs carry the `/tyran` base prefix, the browser pass finds 0 broken links and
91
+ 0 console errors across every page, and the worst mermaid contrast is 5.68:1
92
+ against a floor of 3.
93
+
94
+ **TypeScript stays on 6.** `@astrojs/check` is at its newest release, 0.9.10,
95
+ and still declares `typescript: ^5.0.0 || ^6.0.0` — and `astro check` is what
96
+ the Pages workflow runs, so accepting TS 7 breaks the deploy rather than a
97
+ test. Dependabot now ignores that major with the reason written beside it.
98
+
99
+ The four Dependabot PRs this closes had been open for ten days. They were
100
+ *security* updates, which arrive ungrouped and without the seven-day cooldown,
101
+ so four one-line lockfile changes became four review cycles nobody ran. Both
102
+ tracks are grouped now: one chore a month instead of a queue.
103
+
104
+ ### Three numbers that were wrong
105
+
106
+ The house rule is that a number in the prose is a claim, verified against the
107
+ thing it describes. These three were claims nothing verified.
108
+
109
+ - The README said **1314 unit tests**; the suite has 1405.
110
+ `docs-claims.test.mjs` pins every such claim on the docs surfaces, but each
111
+ of those is about ONE test file and is counted by running it. The README's
112
+ is about the whole suite, which no unit test can count without running the
113
+ suite from inside itself. CI now compares it against the full run it already
114
+ performs for the skipped-test check, so the guard costs nothing.
115
+ - The README said the board has **four tabs**. It has had five since 0.1.24,
116
+ and `docs/board.md` said five throughout. One surface moved, the other did
117
+ not — the failure the two-surfaces rule exists to prevent, on the one
118
+ surface that rule does not name.
119
+ - `templates/config.yaml` keeps **63** comment lines out of 90, not 60.
120
+
121
+ `assets/board-demo.gif` was recorded at 0.1.22 and moves through four tabs, so
122
+ it predates the Settings tab. Its alt text no longer claims to show the whole
123
+ page; the re-record needs a live board and a screen recorder, so it is written
124
+ down as an open item rather than quietly left wrong.
125
+
126
+ ### The browser check had been shrinking
127
+
128
+ `site/scripts/check-browser.mjs` carried a hand-written list of 14 slugs while
129
+ the site had grown to 17 pages. The three it missed — board, overnight, cost —
130
+ were the three newest, which is to say the likeliest to carry a relative link
131
+ nobody had clicked. It reads the content directory now, so the list cannot
132
+ fall behind again. All 17 pass, 18 internal links, 0 broken. A check whose
133
+ coverage silently shrinks as the thing it checks grows is worse than no check,
134
+ because it still prints OK.
135
+
136
+ Astro 7's `preview` daemonizes and returns, so the `npm run preview -- &` in
137
+ both check-script headers no longer described what happens: the server
138
+ outlives the shell that started it and needs `astro preview stop`.
139
+
3
140
  ## 0.1.27 — 2026-08-15
4
141
 
5
142
  The last four items of the munder-difflin plan, and the half of the model
package/README.md CHANGED
@@ -14,6 +14,7 @@
14
14
  <p align="center">
15
15
  <b><a href="https://jjanczur.github.io/tyran/">📖 Documentation</a></b> ·
16
16
  <a href="https://jjanczur.github.io/tyran/getting-started/">Getting started</a> ·
17
+ <a href="https://jjanczur.github.io/tyran/videos/">Videos</a> ·
17
18
  <a href="https://jjanczur.github.io/tyran/architecture/">Architecture</a> ·
18
19
  <a href="https://github.com/jjanczur/tyran/releases/latest">Releases</a>
19
20
  </p>
@@ -22,44 +23,56 @@
22
23
 
23
24
  ## What Tyran is
24
25
 
25
- Every long Claude Code session ends the same way. The context fills up, the
26
- plan is somewhere in the scrollback, and *"the tests pass"* is a sentence
27
- rather than something you can check. Start a new session and you start
28
- explaining from the beginning.
26
+ Your most expensive model just renamed a variable. In the same chat, it judged
27
+ an authentication boundary.
29
28
 
30
- Tyran is an orchestrator. You describe a task; it interviews you until the goal
31
- is unambiguous, sizes it, plans it, and hands each piece to a **dedicated
32
- subagent with fresh context and a model tier matched to how hard that piece
33
- actually is** — cheap for a mechanical sweep, expensive for a security
34
- boundary, never one model for a whole session. They run in parallel, as an
35
- Agent Team where the platform offers one.
29
+ One chat, one model, every job — that is why the bill is high and the work gets
30
+ worse. The context fills up, the plan is somewhere in the scrollback, and
31
+ *"the tests pass"* is a sentence rather than something you can check.
32
+
33
+ **You didn't install a tool. You hired a manager.** You describe the work once;
34
+ he interviews you until the goal is unambiguous — batches of at most four
35
+ questions, each with his recommendation — turns the plan into tickets on a
36
+ board, and hands each piece to a **dedicated subagent with fresh context and a
37
+ model tier matched to how hard that piece actually is.** A good manager doesn't
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
41
+ floor no cost profile or flag can lower.
36
42
 
37
43
  That is a cost lever and a quality lever at the same time. The conductor holds
38
44
  the plan and never accumulates its agents' transcripts, which is where the
39
45
  tokens in a long session actually go; and an agent that never saw the last six
40
46
  failed attempts cannot inherit them, so the second opinion is a real one.
41
47
 
48
+ **Nothing you say is lost.** Remember something halfway through a run and say
49
+ it — it doesn't land in the scrollback, it becomes a ticket. Every decision,
50
+ spawn, report, merge and open question is appended to a journal **committed to
51
+ your repo**, so a restart, a compaction and a colleague on another branch all
52
+ read the same thing.
53
+
42
54
  **It learns your repo while it works.** Setup reads how the repo is really
43
55
  worked — stack, validation commands, how things get deployed — rather than
44
- asking you to describe it. A retrospective after every initiative writes what
45
- it learnt into `.tyran/knowledge/`, and a failure that repeats graduates out of
46
- `MISTAKES.md` into a rule. Meanwhile every decision, spawn, report, merge and
47
- open question is appended to a journal **committed to your repo**, so a
48
- restart, a compaction and a colleague on another branch all read the same
49
- thing.
50
-
51
- All of it is one plugin, and it comes with a **dashboard**: what every agent is
52
- doing right now, which questions are waiting on you, and what the work cost —
53
- in the tokens the platform itself reported, per model, per agent and per
54
- ticket.
55
-
56
- Underneath, **deterministic hooks hold the line**: a report with no raw command
57
- output is rejected, every write is classified against a policy file you own
58
- before it happens, and a commit carrying a secret is refused. Mechanisms rather
59
- than instructions — which is the whole argument.
56
+ asking you to describe it. After every initiative the team runs a retrospective
57
+ on itself, and what it changes is Tyran, never your product code. The same
58
+ failure three times becomes knowledge pasted into every matching handoff; five
59
+ times and it becomes a rule in your `CLAUDE.md`, carrying the dates that earned
60
+ it. Most retros correctly change nothing.
61
+
62
+ All of it lands on one page — a **board**: what every agent is doing right now,
63
+ which questions are waiting on you (answer them there and the run carries on),
64
+ and what the work cost, in the tokens the platform itself reported, per model,
65
+ per agent and per ticket. The conductor gets its own row, so its overhead never
66
+ hides inside the total.
67
+
68
+ Underneath, **a hook decides before the tool ever runs** — none of this is a
69
+ prompt asking nicely. A report with no raw command output is refused: it blocks
70
+ silence, not forgery. Every write is classified against a policy file you own.
71
+ And a commit carrying a secret is refused, even inside a markdown file.
72
+ Mechanisms rather than instructions — which is the whole argument.
60
73
 
61
74
  <p align="center">
62
- <img src="assets/board-demo.gif" width="100%" alt="The Tyran dashboard, recorded live, moving through its four tabs: Overview with what is waiting on you and the strip of running agents each showing the time since it last signalled; Board, where selecting a ticket opens its initiative, agents and spend; Waiting on you, the open questions above the commands that answer them; and Spend, toggling the same split between tokens and cost">
75
+ <img src="assets/board-demo.gif" width="100%" alt="The Tyran dashboard, recorded live, moving through four of its tabs: Overview with what is waiting on you and the strip of running agents each showing the time since it last signalled; Board, where selecting a ticket opens its initiative, agents and spend; Waiting on you, the open questions above the commands that answer them; and Spend, toggling the same split between tokens and cost">
63
76
  </p>
64
77
 
65
78
  <p align="center">
@@ -68,6 +81,31 @@ than instructions — which is the whole argument.
68
81
  lanes, select a card.
69
82
  </p>
70
83
 
84
+ ### Watch it
85
+
86
+ <table>
87
+ <tr>
88
+ <td width="50%" align="center">
89
+ <a href="https://youtu.be/ThulYtbYNXI"><img src="assets/video/a-explainer-16x9.jpg" width="100%" alt="Still from the Tyran explainer: the routing table, with each role resolving to a model tier"></a><br>
90
+ <b><a href="https://youtu.be/ThulYtbYNXI">You Didn't Install a Tool — You Hired a Manager</a></b><br>
91
+ 3:20 · the whole argument, end to end
92
+ </td>
93
+ <td width="50%" align="center">
94
+ <a href="https://youtu.be/vr49hKk9G8g"><img src="assets/video/a-onboarding-16x9.jpg" width="100%" alt="Still from the Tyran onboarding video: the install commands typed into a terminal"></a><br>
95
+ <b><a href="https://youtu.be/vr49hKk9G8g">Your First Session</a></b><br>
96
+ 3:53 · install, run, read the board
97
+ </td>
98
+ </tr>
99
+ </table>
100
+
101
+ <p align="center">
102
+ Three 60-second cuts too —
103
+ <a href="https://www.youtube.com/shorts/2EgRBR0fVRo">the mistake</a> ·
104
+ <a href="https://www.youtube.com/shorts/HKePDLkYDqA">the board</a> ·
105
+ <a href="https://www.youtube.com/shorts/EMcPJj7c0mk">the retro</a> —
106
+ and <a href="https://jjanczur.github.io/tyran/videos/">which to send when</a>.
107
+ </p>
108
+
71
109
  ## What it gives you
72
110
 
73
111
  - **Reports that carry evidence, or are refused.** A `SubagentStop` hook
@@ -204,7 +242,7 @@ open .tyran/state/board.html # xdg-open on Linux, start on Windows
204
242
  — and inside a session you need neither command, because **`/tyran:status`
205
243
  regenerates the board and tells you where it is.**
206
244
 
207
- Four tabs, because the page answers four questions:
245
+ Five tabs, because the page answers five questions:
208
246
 
209
247
  - **Overview** — what is waiting on you, agents running, progress, and what
210
248
  needs a human (blocked lanes **and** blocked agents); then the agent strip,
@@ -220,6 +258,8 @@ Four tabs, because the page answers four questions:
220
258
  - **Spend** — tokens, the amount under your rate card, the conductor's share, a
221
259
  composition bar across input / cache write / cache read / output, and three
222
260
  ranked charts (by model, agent type, ticket) with a tokens/cost toggle.
261
+ - **Settings** — what Tyran is configured to do, every knob with the sentence
262
+ that explains it. Read-only until you pass `--write`, as above.
223
263
 
224
264
  Spend is served rather than embedded, so it is the one thing missing when you
225
265
  open the file directly — [the board](https://jjanczur.github.io/tyran/board/)
@@ -257,7 +297,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
257
297
  fires and who invokes it, is in
258
298
  [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
259
299
  themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
260
- it: 1314 unit tests, run with `node --test "tests/**/*.test.mjs"`.
300
+ it: 1405 unit tests, run with `node --test "tests/**/*.test.mjs"`.
261
301
 
262
302
  ## Documentation
263
303
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.27",
3
+ "version": "0.1.29",
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": {