@jjanczur/tyran 0.1.31 → 0.1.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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.31",
14
+ "version": "0.1.33",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.31",
3
+ "version": "0.1.33",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,364 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.33 — 2026-08-17
4
+
5
+ ### The board was hiding what its own journal already knew
6
+
7
+ Three directory slugs and one blended percentage. The journal has carried a
8
+ written title since it existed — "The kanban board: one screen that answers
9
+ what is going on" — and `crossBoard` summed every initiative's progress before
10
+ throwing the parts away, so an operator reading "47%" across three slugs could
11
+ not tell which was nearly done from which had not started.
12
+
13
+ Each initiative now has its own row: title, progress, and how many questions
14
+ it is waiting on. The payload reads no clock — it ships `last_ts` and the page
15
+ ages it — so `board.mjs --check` stays byte-exact.
16
+
17
+ **This replaced an archive feature, on measurement.** Across 63 distinct real
18
+ journals only 6 were finished-and-archivable while **43 were waiting on a
19
+ question nobody had answered**. The board was never cluttered with completed
20
+ work; it was full of ABANDONED work. Archiving would have touched under 10% of
21
+ initiatives, left the 64-initiative ceiling exactly where it is, and — since
22
+ archivable means 100% merged — pulled the headline percentage DOWN.
23
+
24
+ **Upgrading: one expected `--check` drift.** The payload gains a top-level
25
+ `initiatives` key, so a `board.json` committed by an earlier version no longer
26
+ matches what this one generates. Measured: `board.mjs --check` exits 1 once on
27
+ an upgraded install and 0 after a single regenerate —
28
+
29
+ ```bash
30
+ node scripts/board.mjs --dir .tyran # then commit the three artefacts
31
+ ```
32
+
33
+ `doctor --state` is silent about it either way; the only surface is an
34
+ explicit `--check`, which matters if you run one in CI. The board `schema`
35
+ stays 1 because nothing about the existing keys changed, the same call made
36
+ when `errors_logged` was added.
37
+
38
+ ### Two more things that had never worked and said nothing
39
+
40
+ - **`/run.json` never carried a reset time.** `pickWindow` tested
41
+ `typeof resets_at === 'string'` while every writer produces epoch SECONDS,
42
+ so it returned null for every real payload it was ever given: the run panel
43
+ could say a pause was in force but never when it would end. Live since the
44
+ feature shipped.
45
+ - **The closing checkpoint had no producer.** The projection has closed every
46
+ still-open spawn on `checkpoint phase=closed` since 0.1.31, and nothing ever
47
+ emitted one — 9 of 63 real journals had one. So an agent that finished weeks
48
+ ago still read as live work. The conductor is now told to write it, including
49
+ when an initiative ends because it was ABANDONED, and the test executes the
50
+ command rather than grepping for it.
51
+
52
+ `runState` also reports `limits_mode`: "the gate cannot see" and "the feature
53
+ was never switched on" are different facts with the same symptom.
54
+
55
+ ### An ask offers its recommendation as one click
56
+
57
+ It was shown as text, and the only way to accept it was to retype it into the
58
+ box beneath it. For an operator who is not an engineer, that gap was most of
59
+ the difficulty of the page. The button fills the box rather than submitting,
60
+ so the wording stays editable and the answer stays deliberate.
61
+
62
+ ### Findings are pointed at, not copied
63
+
64
+ Measured across 63 distinct journals: 3 carry any finding, 49 in total, and
65
+ none names a ticket — so they cannot enrich a card. Median claim is 429
66
+ characters and `STATE.md` already renders the full table. The initiative row
67
+ carries a count when it is non-zero and nothing else; a test forbids `claim`
68
+ or `proof` reaching the byte-compared payload.
69
+
70
+ ## 0.1.32 — 2026-08-17
71
+
72
+ ### Overnight mode could never fire, on any install
73
+
74
+ The pause depended on `.tyran/state/usage.json`; only the statusline writes
75
+ it; the statusline writes only when the platform payload carries
76
+ `rate_limits`; and that block is not always sent. Measured on an install
77
+ running `limits: mode: 'pause'` — **no sidecar had ever been written anywhere
78
+ on the machine**, so the configured pause had never once been able to fire.
79
+ The gate fails open, which is why nothing ever said so.
80
+
81
+ The gate now falls back to the platform's own cache in `~/.claude.json`, which
82
+ also removes the one onboarding step no script can perform: registering a
83
+ statusline means writing the operator's settings file, and the plugin is
84
+ refused there by design.
85
+
86
+ **A stale reading is acted on, deliberately.** That cache is refreshed on the
87
+ platform's schedule — measured 83 minutes old during continuous heavy use — so
88
+ under the gate's ten-minute freshness rule it would be discarded every time.
89
+ It is sound because usage inside a window only ever goes UP: a reading taken
90
+ inside the window that is still running is a LOWER BOUND on usage now. If it
91
+ already says 97%, the truth is at least that and pausing is correct; if it
92
+ says less, the gate may fail to pause, which is exactly today's behaviour and
93
+ the safe direction. A reading whose own `resets_at` has passed is discarded —
94
+ that check is what makes the rest safe. Pauses derived this way record
95
+ `lower_bound: true`, because "at least 97%" is a reason to stop and never a
96
+ reason to start.
97
+
98
+ Verified against live telemetry: at the shipped 97% nothing trips (the account
99
+ was at 32%/68%); at a 30% test threshold the weekly window trips with the
100
+ correct resume time.
101
+
102
+ `SIDECAR_RELPATH` had three spellings and `SIDECAR_FRESH_MS` two, across the
103
+ writer, the scheduler and the gate. Nothing fails while they agree, and when
104
+ they stop agreeing the symptom is a pause that silently never fires — the bug
105
+ above. They collapse into `scripts/usage-source.mjs`.
106
+
107
+ Only the two usage windows are read from that file. It also holds the account
108
+ uuid and the email address; a test asserts neither reaches the output.
109
+
110
+ ### Three lifecycle leaks, each measured on real journals first
111
+
112
+ - **`lease-expired` was dead code that looked alive.** It read
113
+ `expires`/`expires_at`/`until`; across every journal on a real machine agents
114
+ wrote **`expiry` 33 times against `expires` 3**, so 33 of 36 recorded
115
+ expiries were invisible.
116
+ - **The schema flagged the field that would have made it work.** No expiry
117
+ spelling was in `DATA_KNOWN`, so recording one tripped `journal-key-unread`
118
+ — the ledger reporting an agent's own diligence back as an anomaly. Same for
119
+ the descriptions agents attach: `purpose` 28, `story` 21, `text` 21.
120
+ - **Worktrees accumulate and nothing had ever looked.** No removal path exists
121
+ in any skill, agent or script, and the journal has no event that can
122
+ represent one being destroyed. Measured: **26 worktrees in one repository,
123
+ 33 GB under another's `.worktrees/`**. New `worktree-accumulating` warning
124
+ above a ceiling of 8 — a handful is the parallel model working as designed.
125
+
126
+ It **reports and does not remove**. Most of those worktrees hold work that
127
+ never CONCLUDED rather than work that finished, so removing the merged ones
128
+ would clear almost nothing while being able to delete something wanted.
129
+
130
+ ### Spend answers "how much", with no configuration
131
+
132
+ The Spend tab could say how many tokens and never how much: `pricing:` was
133
+ hand-authored, the scanner never writes one, so absent was every install.
134
+
135
+ The published list prices now ship as `list-2026-08`. Cache rates are
136
+ published as fixed multiples of base input (1.25x, 2x, 0.1x), so only input
137
+ and output are written down and a test checks all fifteen rows against an
138
+ independently transcribed table. Overriding is per MODEL, not all-or-nothing.
139
+
140
+ This reverses an earlier rule — "Tyran does not know what anyone pays" — which
141
+ conflated two quantities. A subscriber's marginal cost is zero and unknowable;
142
+ what the tokens would list-price at on the API is published and fixed. The
143
+ reversal is conditional on the figure never claiming to be the other, so
144
+ `rate_card` still travels with every amount.
145
+
146
+ **Cache writes are billed at two rates and were counted as one.** A 1-hour
147
+ write costs 2x base input against a 5-minute write's 1.25x, and the transcripts
148
+ carry the split. Reading both the aggregate and the split would double-count,
149
+ so exactly one is read — verified across 1168 consecutive live records where
150
+ the two summed to the aggregate every time. Measured on 1.8 B real tokens: the
151
+ 1-hour line is $175 against the 5-minute line's $70.
152
+
153
+ **A window you choose, because a plan is billed monthly.** `--window
154
+ 30d|period|all`, and three buttons on the tab. `30d` is the default since it
155
+ needs nothing from the account; `period` runs from the subscription
156
+ anniversary and is offered only when that date is readable. The anniversary
157
+ arithmetic clamps short months — a subscription created on the 31st has no
158
+ 31st in February, and naive maths yields a period that has not begun.
159
+
160
+ The plan price sits beside the API figure, and the multiple is shown only
161
+ under a month-shaped window: measured, an all-time total read as "6.9x what
162
+ you pay" where the honest monthly figure was about 11x.
163
+
164
+ **A per-day series**, which this page never had — every other view is a
165
+ snapshot, so nothing could answer "am I getting cheaper". It shows the full
166
+ history whatever window is selected, since a chart that shrank with the window
167
+ could not show you that last month was worse.
168
+
169
+ ### The reviewer can fix what it finds
170
+
171
+ The property worth protecting was never "a reviewer cannot type" — it is that
172
+ nobody approves their own code, and those come apart. The reviewer holds
173
+ `Edit`, and the verdict is three-valued: a diff it touched can only come back
174
+ `REVISED`, which still owes a second read, and that read is cheap because the
175
+ fix is already written. No `Write` or `NotebookEdit`: authoring files is
176
+ designing, not reviewing.
177
+
178
+ An open operator ask now goes in the verdict LINE. Field-measured: a reviewer
179
+ raised a gate inside the body of an APPROVE, the conductor read the first
180
+ word, merged, and the question sat unanswered for thirty minutes.
181
+
182
+ **Subagents could not reach MCP at all.** `tools:` is an exhaustive allowlist,
183
+ so naming six built-ins silently stripped every `mcp__*` tool from the scout
184
+ and the reviewer — the scout's own description promises reconnaissance over
185
+ "its data", which was unreachable. Grants stay gated: write-guard's matcher
186
+ already carries `mcp__.*`.
187
+
188
+ ### Two gate refusals that were wrong
189
+
190
+ - A backslash-escaped separator started a new segment, so `grep -nE 'A\|B' f`
191
+ split in two and an ordinary read was refused. `\<sep>` is never an operator
192
+ in any shell quoting context — verified against `/bin/sh` with a side-effect
193
+ oracle over 34 join constructions, zero divergences. The lexer stays
194
+ quote-BLIND on purpose: a naive quote tracker is broken by one apostrophe,
195
+ which swallows a `;` and makes a `git push` invisible to the deployment
196
+ check.
197
+ - `^id_[a-z0-9]+$` was really "any identifier starting with id_", and these
198
+ rules run over every literal WORD of a command — so `ID_ISSUED` and
199
+ `ID_TOKEN` were refused as ssh private keys. Now anchored on OpenSSH's own
200
+ key-type names, keeping hardware keys and per-host suffixes. Declared cost: a
201
+ key with an invented stem is no longer matched by name, though `.ssh/` still
202
+ catches it and so does gitleaks at push.
203
+
204
+ ### Setup asks one question, in words a non-engineer can answer
205
+
206
+ Sales and marketing people run this now, and four entries shaped
207
+ `field: source` is where they stop. The scan carries a `plain` object: one
208
+ question, its evidence restated without jargon, at most two options, and a
209
+ list of what the repository already answered. P3 is not offered — a menu makes
210
+ every item look like a normal choice, and it stays something a person says in
211
+ their own words.
212
+
213
+ ### Installation reaches the dashboard now
214
+
215
+ Install was four steps, a restart, and then a board nobody opened. Every one
216
+ of those is a place to stop, and the last one mattered most: `--serve` printed
217
+ a URL to a terminal and **nothing ever launched a browser**, so the screen
218
+ where Tyran becomes legible was the one thing installation never reached.
219
+
220
+ `install.sh` does everything a machine can:
221
+
222
+ ```bash
223
+ curl -fsSL https://raw.githubusercontent.com/jjanczur/tyran/main/install.sh | sh
224
+ ```
225
+
226
+ Node version check first, because every hook shells out to `node` and an old
227
+ one does not fail at install time — it fails later as a gate that cannot run,
228
+ which is the hardest thing for a non-technical operator to read. Then the
229
+ plugin, then the pinned scanner, then the prompt to paste after the restart.
230
+
231
+ The restart is the one step that stays manual and it is not a shortcut not
232
+ taken: Claude Code loads plugins at startup and nothing inside a session can
233
+ make the app reload itself. So it is stated plainly and put last.
234
+
235
+ `board.mjs --serve --open` launches the browser, best-effort and never fatal —
236
+ a headless machine or an SSH session leaves the server running and the URL
237
+ printed, exactly where things were before. `--open` without `--serve` is a
238
+ usage error, like `--write`.
239
+
240
+ Setup gained two steps: install the scanner before anything needs it, and
241
+ **look for pre-existing secrets before the operator hits them**. A repository
242
+ whose history already holds a key is common, and the gate handles it badly by
243
+ surprise — nothing is scanned until someone edits that file, and then every
244
+ commit touching it is refused, permanently, for a reason years old. Setup now
245
+ says what is there and explains the choice, including the part that is easy to
246
+ leave out: a tracked baseline makes the tool quiet, it does not make the key
247
+ safe, and if the repo is public that key is already burned.
248
+
249
+ ### The knowledge store was write-only, and nothing said so
250
+
251
+ Measured on a real install: `knowledge.mjs brief '**'` returned **1 of 31
252
+ entries**. The other thirty were dropped by the 4000-codepoint budget, and
253
+ 104,178 codepoints of hard-won detail — migration-number races, TEST/PROD
254
+ schema drift, a deploy gate that silently blocks on the commit author — had
255
+ been accumulating for months and reaching nobody.
256
+
257
+ That is the opposite of the failure people expect from a growing store. It is
258
+ not expensive to read; it is **unread**, while growing without bound.
259
+
260
+ Every piece of the machinery was already correct and none of it added up. The
261
+ budget is deliberately the pressure that keeps entries scoped. Each brief
262
+ already names what it omitted. `doctor` already warned per oversized entry —
263
+ five times on that install. What nobody had was the total, and five local
264
+ tidy-up notes are not the same message as "your knowledge store is 97%
265
+ unread". Only the second one gets acted on.
266
+
267
+ `knowledge.mjs audit` reports it: how many entries could reach ONE brief, how
268
+ many could not, and — the diagnostic that matters most — which entries are so
269
+ wide they cannot appear **even alone**, where no budget any caller passes will
270
+ ever reach them. Eight of that install's thirty-one are in that state; the
271
+ widest is 10,210 codepoints, two and a half times the whole budget.
272
+ `doctor --state` carries the same number as `knowledge-store-unreachable`
273
+ (`info` — a store outgrows the budget in the ordinary course of being useful).
274
+
275
+ It measures and never edits. Which of two overlapping entries is the true one
276
+ is a judgement, and a script that guessed would delete exactly the detail the
277
+ store exists to hold — so consolidation is a retrospective step that writes a
278
+ **new** file for review and leaves the original untouched.
279
+
280
+ ### The prerequisite that blocked day one
281
+
282
+ The secrets gate refuses every commit and push until `gitleaks` exists, and
283
+ it refuses rather than warning for a reason that has not changed. What had
284
+ been left with the operator is the *installing*: some people adopting Tyran
285
+ have no Homebrew, no admin rights, or are on Windows, and their realistic
286
+ answer to "install it and re-run" is not a safer repository — it is switching
287
+ the hook off. A gate nobody can satisfy protects nothing, which is the same
288
+ argument that made `.tyran/config.yaml` AUTO.
289
+
290
+ `scripts/ensure-gitleaks.mjs` fetches it: pinned version **and** pinned
291
+ SHA-256 per platform, taken from the release's own checksums, which is the
292
+ thing `ci.yml` has always done moved to where a user can reach it. A mismatch
293
+ deletes the download and installs nothing — this writes an executable that
294
+ something else later runs, and a scanner that has been replaced reports clean
295
+ on everything.
296
+
297
+ It installs to `~/.tyran/bin/`. The first version of this put it under
298
+ `<repo>/.tyran/bin/`, which is worse in a way worth recording: a path inside
299
+ the repository travels with a clone, so a planted binary reporting clean on
300
+ everything would arrive **with the checkout** — the attack the tracked-only
301
+ rule for `.gitleaksignore` already prevents, reopened through a file that is
302
+ not even in a diff. Under HOME the scanner is the operator's machine, exactly
303
+ like PATH, and one install serves every repository on it. PATH is still
304
+ consulted first: a gitleaks you installed yourself is never silently
305
+ displaced by whatever version this repo pins.
306
+
307
+ ### Writing a prompt is now a top-tier job
308
+
309
+ `retro` was routed at `work` and reached `deep` only under `--profile full`,
310
+ so the agent that writes skills, agents and prompts — the text every later
311
+ session obeys — ran on the middle model, and `--profile eco` kept it there.
312
+
313
+ A new `authoring` role sits at `top` at every profile, with `top` and `max`
314
+ floors under it. Separated from `retro` rather than raising the whole of it,
315
+ because retro does two unlike things with one agent: folding a ledger, which
316
+ the middle model does fine, and authoring. The argument is `security-review`'s
317
+ in a stronger form — a bad security verdict costs one merge, while a bad
318
+ prompt misroutes every run that reads it for as long as it ships, and it is
319
+ the one output nothing downstream checks, because a skill that reads plausibly
320
+ passes review.
321
+
322
+ ### A duplicate ledger id is refused
323
+
324
+ Measured in the field: two implementers running in parallel each worked out an
325
+ id for themselves, both were honoured, and the ledger kept two `F-7`s. History
326
+ is append-only, so "see F-7" stays ambiguous forever and nothing detects it
327
+ later.
328
+
329
+ `append` now refuses a caller-supplied `id` that is **already used for that
330
+ event type**. Deliberately not the broader fix of refusing every explicit id:
331
+ that removes a documented capability — an explicit id still wins, and a test
332
+ pins it — to prevent a failure that only occurs on collision. A fresh explicit
333
+ id still passes, `ticket.created` is unaffected because its ids come from the
334
+ plan, and the check runs under the write lock so two concurrent writers cannot
335
+ both pass it.
336
+
337
+ ### Refusals you can paste
338
+
339
+ The multi-remote push refusal is correct — excluding commits present on ANY
340
+ remote let a key held on a private upstream reach a public origin unscanned —
341
+ but it was reported twice, from two installs, as a false positive, and both
342
+ reporters routed around it instead of satisfying it. The old text handed over
343
+ `git push <remote> <branch>`, a shape to translate rather than a line to run.
344
+
345
+ Everything needed to write the real command was already in hand, so it is
346
+ written: one runnable line per remote, with the branch filled in.
347
+
348
+ ### Reviewers stop retyping evidence
349
+
350
+ `tyran:reviewer` has no MCP tools, so a database row or an API response
351
+ someone else fetched reaches it as text in a handoff — and text in a handoff
352
+ gets retyped. Measured on a production run: **1.6% of hand-copied values were
353
+ silently wrong**, which makes a reviewer that mistranscribes evidence worse
354
+ than no reviewer, because the verdict carries authority the numbers do not.
355
+
356
+ The roster is unchanged, because it cannot express the fix: `tools:` is a
357
+ static list shipped in the plugin and MCP tool names differ on every install.
358
+ The prompt closes it instead — require the raw bytes on disk and `Read` them,
359
+ rather than reasoning about a retyped copy. A value read from a file is
360
+ evidence; a value pasted into a sentence is a claim about evidence.
361
+
3
362
  ## 0.1.31 — 2026-08-17
4
363
 
5
364
  Seven things the journal had recorded and nothing was reading. The theme is
package/README.md CHANGED
@@ -123,8 +123,10 @@ Mechanisms rather than instructions — which is the whole argument.
123
123
  profile or risk flag can cross.
124
124
  - **A spend ledger.** `npx @jjanczur/tyran cost` reports what the work cost, in
125
125
  the tokens the platform itself reported, per model, per agent type and per
126
- ticket — read out of the transcripts Claude Code already writes. Money
127
- appears only under a rate card you write: Tyran does not know what you pay.
126
+ ticket — read out of the transcripts Claude Code already writes. Dollars
127
+ need no setup: the published list prices ship, so a fresh install shows what
128
+ the run would have cost through the API, next to what your plan costs a
129
+ month. Write a rate card only to override them.
128
130
  - **It can run overnight, because the usage limit is a wind-down and not a
129
131
  crash.** The platform's own behaviour at the limit is a cliff: calls start
130
132
  failing mid-flight and agents die between a write and its commit. Near the
@@ -176,7 +178,17 @@ count, not the price of a model.
176
178
 
177
179
  ## Install
178
180
 
179
- Inside Claude Code:
181
+ One command, then one restart, then one paste:
182
+
183
+ ```bash
184
+ curl -fsSL https://raw.githubusercontent.com/jjanczur/tyran/main/install.sh | sh
185
+ ```
186
+
187
+ It checks Node, installs the plugin, installs the secrets scanner the write
188
+ gate needs, and prints the prompt to paste after you restart — which runs
189
+ setup and opens the dashboard in your browser.
190
+
191
+ Or do it by hand, inside Claude Code:
180
192
 
181
193
  ```text
182
194
  /plugin marketplace add jjanczur/tyran
@@ -297,7 +309,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
297
309
  fires and who invokes it, is in
298
310
  [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
299
311
  themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
300
- it: 1451 unit tests, run with `node --test "tests/**/*.test.mjs"`.
312
+ it: 1535 unit tests, run with `node --test "tests/**/*.test.mjs"`.
301
313
 
302
314
  ## Documentation
303
315
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: reviewer
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 a binary APPROVE or CHANGES-REQUESTED with numbered, executable counterexamples. Never reviews its own code.
4
- tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
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__*
5
5
  ---
6
6
 
7
7
  You are a reviewer. You review ANOTHER agent's work, never your own.
@@ -9,10 +9,47 @@ You are a reviewer. You review ANOTHER agent's work, never your own.
9
9
  **Reply in the language the conductor writes to you in. Anything written to
10
10
  disk is in English.**
11
11
 
12
- You have no editing tools on purpose: a reviewer who can fix what they found
13
- ends up approving their own patch. This removes the easy path, not every path
14
- — `Bash` can still write — so treat it as a boundary you keep, not a wall
15
- that keeps you.
12
+ **You may fix what you find. Fixing costs you the right to approve it.**
13
+
14
+ You have `Edit`, and it is there because describing a one-line fix in prose,
15
+ waiting for the conductor to route it, and having the author re-derive it from
16
+ your description is a slow way to reach a change you had already worked out.
17
+ Write it instead.
18
+
19
+ What you may never do is bless your own work. So the verdict is three-valued,
20
+ and the rule is mechanical rather than a matter of judgement: **if you touched
21
+ the diff, `APPROVE` is not available to you.** Your verdict is `REVISED`, and
22
+ the second pair of eyes is cheap precisely because the fix is already written —
23
+ someone reads a small concrete delta instead of re-deriving one from a
24
+ paragraph. A reviewer who edits and then approves has reviewed nothing; that is
25
+ the entire failure this rule exists to stop, and it is the only one.
26
+
27
+ Two boundaries on the grant, both narrow on purpose:
28
+
29
+ - **`Edit` only — no `Write`, no `NotebookEdit`.** You change lines that exist.
30
+ A reviewer who creates files has stopped reviewing and started designing, and
31
+ the tool list says so rather than a paragraph asking you to be disciplined.
32
+ - **Fix what you found. Do not redesign.** If the right answer is "this whole
33
+ approach is wrong", that is `CHANGES-REQUESTED` with the argument, not a
34
+ rewrite. The pull toward patching a symptom you can reach, instead of
35
+ reporting a cause you cannot, is the real cost of holding this tool — notice
36
+ it.
37
+
38
+ `Bash` can still write, and so can an MCP tool whose name this plugin has never
39
+ seen. **Verify, never mutate**: query the database, do not migrate it; read the
40
+ issue, do not close it.
41
+
42
+ **Never retype evidence. Go and get it.** A database row or an API response
43
+ someone else fetched reaches you as text in the handoff, and text in a handoff
44
+ gets retyped. Measured on a production run: 1.6% of hand-copied values were
45
+ silently wrong, which makes a reviewer that mistranscribes evidence worse than
46
+ no reviewer, because the verdict carries authority the numbers do not deserve.
47
+ You have the operator's MCP servers, so the first move is to re-run the query
48
+ yourself and compare. When you genuinely cannot obtain the output — the tool
49
+ is absent, the credential is not yours — require the raw bytes on disk and
50
+ `Read` them: reply asking for the path, do not reason about the retyped copy.
51
+ A value you fetched or read is evidence; a value someone pasted into a
52
+ sentence is a claim about evidence.
16
53
 
17
54
  1. **Read the whole diff** plus the story file that holds the acceptance
18
55
  criteria. **Follow the `code-review` skill for the sweep** — it carries the
@@ -47,9 +84,13 @@ that keeps you.
47
84
  without one loses the author's work with no record of what was in it.
48
85
  3. **Check the optimization section** — whether what the author claims is
49
86
  genuinely in the code, not just in the write-up.
50
- 4. **The verdict is binary.** APPROVE, with minor notes routed to `NOTES.md`;
51
- or CHANGES-REQUESTED with a numbered list — what, where, why. No
52
- generalities.
87
+ 4. **The verdict is one of three words**, and the first line of your report is
88
+ that word alone. APPROVE, with minor notes routed to `NOTES.md`; REVISED if
89
+ you edited anything, listing every file you touched and why; or
90
+ CHANGES-REQUESTED with a numbered list — what, where, why. No generalities.
91
+ - **REVISED is not a soft APPROVE.** It means the work is now partly yours
92
+ and still owes someone a read. Say in one line what a second reader should
93
+ look at hardest, because you are the one person who cannot judge it.
53
94
  - **Every counterexample must be EXECUTABLE**: concrete input, expected
54
95
  behaviour, so it can be pinned as a test. A finding that cannot be pinned
55
96
  cannot be verified as fixed.
@@ -66,6 +107,12 @@ that keeps you.
66
107
  '...' --default '...'` — name the `Q-<n>` in your review, and give a
67
108
  verdict on everything else. Holding a whole review open on one question
68
109
  the operator has not seen is how a queue becomes a stall.
110
+ - **An open ask goes in the verdict LINE, not the body**: write
111
+ `APPROVE — BLOCKED ON Q-3` and nothing else on that line. Measured on a
112
+ field run: a reviewer raised an operator gate inside the body of an
113
+ APPROVE, the conductor read the first word, merged, and the question sat
114
+ unanswered for thirty minutes. Anything a merge must wait for has to
115
+ survive being read by someone who reads one line.
69
116
  5. **Say what you did NOT check.** Platform you did not run on, concurrency
70
117
  you did not exercise, the input class you skipped. This section is a merge
71
118
  gate, not a courtesy: the conductor resolves every item as measured,
package/agents/scout.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: scout
3
3
  description: Fast, cheap reconnaissance over a repo, its documentation, its data or external sources, changing nothing. Returns short, concrete findings with the file path or URL that proves each one. Used by the conductor at the start of a task and through the research phase of a large initiative.
4
- tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
4
+ tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, mcp__*
5
5
  ---
6
6
 
7
7
  You are the scout. You find things out. You change nothing.
@@ -28,7 +28,13 @@ disk is in English.**
28
28
  4. **Verify premises about DATA by measuring, read-only.** "The field is in
29
29
  the schema" is not "the field is in the data". If the handoff assumes
30
30
  something about a real dataset, check the dataset and report what you
31
- actually saw.
31
+ actually saw. You have the operator's MCP servers for exactly this — a
32
+ database, an issue tracker, a browser — and they are the only way to reach
33
+ data that is not a file. Rule 1 governs them and it governs them harder:
34
+ the tool list cannot tell a read from a write, because an MCP server names
35
+ its own tools and this plugin has never seen yours. `execute_sql` reads
36
+ until the statement is an `INSERT`. Run the query; never the migration,
37
+ the mutation, the deploy or the delete.
32
38
  5. **Distinguish what you measured from what you inferred.** Label them. An
33
39
  inference presented as an observation is the most expensive thing you can
34
40
  hand back, because it survives review by sounding like a fact.
package/bin/tyran.mjs CHANGED
@@ -56,6 +56,14 @@ export const COMMANDS = {
56
56
  'scan-repo.mjs',
57
57
  'Deterministic repo scan for /tyran:setup — establishes what it can, marks what needs confirmation, never guesses.',
58
58
  ],
59
+ 'ensure-gitleaks': [
60
+ 'ensure-gitleaks.mjs',
61
+ 'Install the pinned, checksummed gitleaks the secrets gate needs, for a machine that has none.',
62
+ ],
63
+ migrate: [
64
+ 'migrate.mjs',
65
+ 'Move a pre-0.1.9 .tyran/initiatives/ directory under state/. Previews by default; never overwrites.',
66
+ ],
59
67
  tiers: [
60
68
  'tiers.mjs',
61
69
  'Resolve a Tyran role to a model alias via .tyran/config.yaml, the one place model names are allowed to live.',
@@ -234,7 +234,28 @@ export const SECRET_READ_RULES = Object.freeze([
234
234
  match: (b) => /^\.env(\.[^/]*)?$/i.test(b) && !/\.(example|sample|template|dist|defaults?|schema)$/i.test(b),
235
235
  },
236
236
  { id: 'private-key-file', on: 'basename', match: (b) => /\.(pem|key|p12|pfx|jks|keystore|kdbx|asc|ppk)$/i.test(b) },
237
- { id: 'ssh-private-key', on: 'basename', match: (b) => /^id_[a-z0-9]+$/i.test(b) },
237
+ // Anchored on OpenSSH's actual key-type names. `^id_[a-z0-9]+$` was really
238
+ // "any identifier starting with id_", and because `shellPathFindings` runs
239
+ // these rules over every literal WORD of a command — not only over things
240
+ // shaped like paths — it refused `ID_ISSUED`, `ID_TOKEN`, `ID_SPEND`, and
241
+ // any other SCREAMING_SNAKE constant in that namespace. Measured live: a
242
+ // grep for `ID_ISSUED` was refused as an ssh private key.
243
+ //
244
+ // `_sk` covers FIDO/hardware keys; the trailing group covers the very common
245
+ // per-host naming (`id_rsa_github`, `id_ed25519_work`, `id_rsa-personal`).
246
+ // Case-folding stays: on macOS and Windows `ID_RSA` and `id_rsa` are one
247
+ // file, and dropping /i would let a rename walk past this rule.
248
+ //
249
+ // DECLARED COST: a private key with a non-algorithm stem — `id_deploy`,
250
+ // `id_ci` — no longer matches HERE. Inside any `.ssh/` directory the
251
+ // `ssh-directory` rule below still catches it, and the secrets gate still
252
+ // catches the key's BYTES at commit and push. This list is a denylist and
253
+ // has always been documented as incomplete.
254
+ {
255
+ id: 'ssh-private-key',
256
+ on: 'basename',
257
+ match: (b) => /^id_(rsa1?|dsa|ecdsa|ed25519|xmss)(_sk)?([_-][a-z0-9_-]+)?$/i.test(b),
258
+ },
238
259
  { id: 'credentials-file', on: 'basename', match: (b) => /^\.?credentials(\.[a-z0-9]+)?$/i.test(b) },
239
260
  { id: 'netrc', on: 'basename', match: (b) => /^_?\.?netrc$/i.test(b) },
240
261
  { id: 'registry-auth', on: 'basename', match: (b) => /^\.(npmrc|pypirc|pgpass|dockercfg)$/i.test(b) },