@jjanczur/tyran 0.1.40 → 0.1.43
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +316 -0
- package/README.md +13 -3
- package/agents/implementer.md +5 -2
- package/agents/retro.md +9 -6
- package/agents/reviewer.md +3 -1
- package/agents/scout.md +2 -1
- package/agents/verifier.md +2 -1
- package/bin/tyran.mjs +1 -1
- package/hooks/HOOK-CONTRACT-MEASURED.md +6 -1
- package/hooks/scripts/hook-io.mjs +66 -8
- package/hooks/scripts/policy-gate.mjs +141 -9
- package/package.json +4 -1
- package/scripts/board-html.mjs +264 -19
- package/scripts/board.mjs +134 -6
- package/scripts/doctor.mjs +164 -5
- package/scripts/journal.mjs +17 -1
- package/scripts/knowledge.mjs +219 -20
- package/scripts/project.mjs +9 -1
- package/scripts/scan-repo.mjs +17 -1
- package/scripts/schema.mjs +125 -3
- package/scripts/settings.mjs +114 -3
- package/skills/retro/SKILL.md +26 -0
- package/skills/run/SKILL.md +4 -2
- package/skills/setup/SKILL.md +20 -0
- package/templates/config.yaml +28 -0
- package/templates/knowledge.yaml +5 -0
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
{
|
|
12
12
|
"name": "tyran",
|
|
13
13
|
"description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
|
|
14
|
-
"version": "0.1.
|
|
14
|
+
"version": "0.1.43",
|
|
15
15
|
"source": "./",
|
|
16
16
|
"author": {
|
|
17
17
|
"name": "Jacek Janczura",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.43",
|
|
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,321 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.43 — 2026-08-18
|
|
4
|
+
|
|
5
|
+
### One switch that opens the gate, and four things it cannot reach
|
|
6
|
+
|
|
7
|
+
Tyran refuses things a less-technical operator cannot reason about: a `.env`
|
|
8
|
+
read, a path outside the repository, a `GATED` write from a subagent, a push
|
|
9
|
+
past the deployment class. Every one of those refusals is defensible and every
|
|
10
|
+
one of them is a wall, and until now there was no way to turn any of it down.
|
|
11
|
+
The knobs that existed — `autonomy:` and `main_writable_paths:` — are narrow,
|
|
12
|
+
and neither is the switch people were asking for.
|
|
13
|
+
|
|
14
|
+
`boundaries:` in `.tyran/config.yaml` is that switch. Five flags and a preset:
|
|
15
|
+
|
|
16
|
+
```yaml
|
|
17
|
+
boundaries:
|
|
18
|
+
preset: open
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`outside_repo` stops refusing paths outside the repo, for **every** actor
|
|
22
|
+
rather than the main thread only — which is the difference between this and
|
|
23
|
+
`main_writable_paths:`, and it is deliberate: a flag that says agents may work
|
|
24
|
+
outside the repository is useless if it excludes the agent that does the work.
|
|
25
|
+
`credentials` lets `.env` and friends be read on `Read`, `Grep` and in shell
|
|
26
|
+
text. `path_classes` makes your own `GATED`/`KERNEL` rules advisory for writes.
|
|
27
|
+
`push` skips the deployment-class analysis whole — refspec and alias refusals
|
|
28
|
+
included, because with no destination left to judge, refusing a command for
|
|
29
|
+
being unreadable to a check that is switched off is noise, not safety.
|
|
30
|
+
`prompts: skip` is the one people mean by "skip permissions".
|
|
31
|
+
|
|
32
|
+
**An explicit key beats the preset in both directions**, so `preset: open` with
|
|
33
|
+
`credentials: refuse` is a repo that wants room to work but not its own keys
|
|
34
|
+
read, and `preset: strict` with `outside_repo: allow` is one door.
|
|
35
|
+
|
|
36
|
+
### `permissionDecision: "allow"` became sayable, and stayed unreachable by accident
|
|
37
|
+
|
|
38
|
+
`prompts: skip` needed something the hook runtime deliberately did not have.
|
|
39
|
+
The old invariant was *"there is no way to emit `allow` from this runtime, and
|
|
40
|
+
a test pins that"* — sound, because `allow` does not mean "this gate is
|
|
41
|
+
satisfied", it means "approve this call and skip the prompt", and a gate
|
|
42
|
+
emitting it for everything it did not object to would be approving the session.
|
|
43
|
+
|
|
44
|
+
The invariant is now narrower and strictly harder to hold: **`PASS` never
|
|
45
|
+
becomes `allow`, and no failure mode does either.** Auto-approval requires a
|
|
46
|
+
handler to return `{decision: 'allow'}` on purpose. A throw, a timeout, an
|
|
47
|
+
overrun budget, a malformed input and an unrecognised verdict are all still
|
|
48
|
+
refusals, and the test that used to assert unreachability now asserts that
|
|
49
|
+
list — including the case that actually bites, a handler that overruns and
|
|
50
|
+
*then* returns an approval, whose verdict is discarded.
|
|
51
|
+
|
|
52
|
+
In the gate it is one line in one place. `handle()` rewrites a verdict only
|
|
53
|
+
when it was already `PASS`; a `deny`, an `ask` and a `PolicyFailure` are
|
|
54
|
+
returned untouched. A gate that could not complete its check must not
|
|
55
|
+
auto-approve, whatever the config says.
|
|
56
|
+
|
|
57
|
+
### The floor, which is the part that makes the rest safe to ship
|
|
58
|
+
|
|
59
|
+
`.tyran/config.yaml` is class `AUTO`, so an agent can widen these itself. That
|
|
60
|
+
is the trade `autonomy:` already made and it is recorded as one declared limit
|
|
61
|
+
rather than two, because it is one fact. What makes it acceptable is that the
|
|
62
|
+
floor is mechanical:
|
|
63
|
+
|
|
64
|
+
- **Secret scanning is untouched.** `gitleaks` runs from the secrets gate, a
|
|
65
|
+
different hook that never learns the word `boundaries`, and `deny` from any
|
|
66
|
+
hook beats `allow` from another. Pinned twice: a source assertion that the
|
|
67
|
+
file never reads the block, and a real scan — a repo configured as
|
|
68
|
+
permissively as the schema allows still refuses a commit carrying a private
|
|
69
|
+
key, with coverage verified.
|
|
70
|
+
- **`BOUNDARY_FLOOR_GLOBS`** is `SHELL_PROTECTED_GLOBS` plus `.tyran/STOP`, and
|
|
71
|
+
`path_classes: allow` consults the floor *before* the flag. The enforcement
|
|
72
|
+
hooks, the policy that classifies them, the hook registry, and the operator's
|
|
73
|
+
brake. A flag the loop can use to clear its own stop signal is not a flag.
|
|
74
|
+
This changes nothing about what a policy file may say — it closes a new door
|
|
75
|
+
rather than reopening an old one.
|
|
76
|
+
- **Every unreadable answer is strict.** A missing config, an unparseable one,
|
|
77
|
+
an oversized one, and any value the schema rejects all resolve to every
|
|
78
|
+
boundary ON. `credentials: yes` is not `allow`. This is `limitsOf`'s doctrine
|
|
79
|
+
with the sign flipped: an out-of-range limit falls back to a default, but a
|
|
80
|
+
security flag must never *relax* on input nobody can read.
|
|
81
|
+
|
|
82
|
+
### On the dashboard, with the confirmation it already knew how to ask for
|
|
83
|
+
|
|
84
|
+
The Settings tab has a "What agents may touch" section with all six controls.
|
|
85
|
+
Loosening any of them demands the same second, deliberate act that raising
|
|
86
|
+
`autonomy` does, and the token is the new value itself rather than a boolean,
|
|
87
|
+
so a caller cannot satisfy it by sending `confirm: true` alongside whatever
|
|
88
|
+
value it liked. Tightening is one click, always.
|
|
89
|
+
|
|
90
|
+
That took deleting something rather than adding it: `applySetting` had an
|
|
91
|
+
`if (id === 'autonomy')` special case, and every knob added beside it would
|
|
92
|
+
have had to remember to extend that line — which is exactly how a
|
|
93
|
+
boundary-loosening control ships with no confirmation at all. The catalogue
|
|
94
|
+
carries a `widening` descriptor now and the check reads it.
|
|
95
|
+
|
|
96
|
+
The block is written out in full by `scan-repo.mjs` and in
|
|
97
|
+
`templates/config.yaml`, at its strict values, for the same reason `limits:` is:
|
|
98
|
+
`yaml-patch` refuses to invent a key, so an absent block is a section of the
|
|
99
|
+
dashboard nobody can use. `doctor` reports `boundaries-absent` (info) for a
|
|
100
|
+
config written before this release, and `boundaries-relaxed` (warning) whenever
|
|
101
|
+
anything is loose — naming which flags. Relaxing a boundary removes refusals,
|
|
102
|
+
so nothing else in a session will ever mention it again.
|
|
103
|
+
|
|
104
|
+
Documented on both surfaces: `configuration` carries the reference and the
|
|
105
|
+
cost, `policy-gate` gains "Turning the gate down" and extends declared limit 6,
|
|
106
|
+
`hooks` restates the approval contract, `board` covers the new controls, and
|
|
107
|
+
`faq` answers it in the words somebody would actually search for.
|
|
108
|
+
|
|
109
|
+
## 0.1.42 — 2026-08-18
|
|
110
|
+
|
|
111
|
+
### The board stopped throwing you off the page you were reading
|
|
112
|
+
|
|
113
|
+
Six defects, all reported by an operator using the board rather than found by
|
|
114
|
+
a test, and every one of them a place where the page knew something and did
|
|
115
|
+
not act on it.
|
|
116
|
+
|
|
117
|
+
**The tab lived in a local variable.** The page reloads itself every 30
|
|
118
|
+
seconds; tab state did not survive that, so anyone reading Spend was returned
|
|
119
|
+
to Overview twice a minute. The open tab now travels in the URL fragment, which
|
|
120
|
+
also makes `#questions` a link you can send someone. `replaceState`, not an
|
|
121
|
+
assignment to `location.hash` — the latter pushes a history entry per reload,
|
|
122
|
+
and Back then walks backwards through half an hour of refreshes instead of
|
|
123
|
+
leaving the page. A `hashchange` listener answers the other half: changing only
|
|
124
|
+
the fragment is a same-document navigation that reloads nothing, so without it
|
|
125
|
+
a deep link into an already-open page moved the URL and nothing else. That half
|
|
126
|
+
is invisible to source reading and was found in a browser.
|
|
127
|
+
|
|
128
|
+
**Spend now holds the refresh timer, as Settings already did.** Nothing on it
|
|
129
|
+
is live: it is one scan of your transcripts, and reloading under a reader
|
|
130
|
+
comparing two rows re-runs the scan to redraw numbers that did not move. The
|
|
131
|
+
lane filter holds it too, and releases when cleared. Overview and Board are
|
|
132
|
+
never held — a board that quietly stopped updating at midnight is the failure
|
|
133
|
+
this page exists to prevent.
|
|
134
|
+
|
|
135
|
+
**An initiative row is a button now.** It was the one thing on the page you
|
|
136
|
+
could read and not open. Selecting one opens the ticket detail's own shape:
|
|
137
|
+
directory, state, tickets merged, findings, when it last moved — and the
|
|
138
|
+
documents beside its journal, which the board has listed as paths since it
|
|
139
|
+
learned to list them and could not show.
|
|
140
|
+
|
|
141
|
+
`GET /doc.json?init=…&name=…` serves those five files, and it takes **no path**.
|
|
142
|
+
`name` must equal a member of `INITIATIVE_FILES`; `init` must equal a directory
|
|
143
|
+
`state/` actually contains. Nothing from the request is joined into a path
|
|
144
|
+
until it has matched one of those two lists, so traversal is refused by never
|
|
145
|
+
being a candidate rather than by a filter someone has to keep ahead of. The
|
|
146
|
+
text is invisible-escaped like every other journal-side value that reaches a
|
|
147
|
+
human, capped at 200 000 codepoints, and rendered by nothing — these documents
|
|
148
|
+
are agent-written, out of reports about other repositories. Reading is not
|
|
149
|
+
behind `--write`: that flag draws its line at changing the repository.
|
|
150
|
+
|
|
151
|
+
**Finished and abandoned stopped looking identical.** A percentage cannot tell
|
|
152
|
+
them apart, and the board had nothing else — measured across 63 real journals,
|
|
153
|
+
43 sat on an unanswered question and 6 were genuinely done. A `checkpoint`
|
|
154
|
+
whose phase is the reserved word `closed` is the only event that ends an
|
|
155
|
+
initiative, and it already closes that initiative's open spawns; the row now
|
|
156
|
+
says `FINISHED`, carries the timestamp, sorts last and leaves the "waiting on
|
|
157
|
+
you" count. It is deliberately **not** a deployment claim: no event in the
|
|
158
|
+
closed set records a deploy, so the board does not imply one.
|
|
159
|
+
|
|
160
|
+
**The answer box grew the keystroke everyone tried.** ⌘/Ctrl+Enter sends, and
|
|
161
|
+
the placeholder says so — "Answer" was always the send button, but a labelled
|
|
162
|
+
verb beside a text box reads as a mode switch. Bare Enter still inserts a
|
|
163
|
+
newline, on purpose: answers are sentences, which is why the field is a
|
|
164
|
+
textarea, and what it sends is appended to a journal that can never take it
|
|
165
|
+
back.
|
|
166
|
+
|
|
167
|
+
**And the three `npx answer` commands folded away.** They are the only route on
|
|
168
|
+
a read-only board or one opened over `file://`, so they cannot be removed — but
|
|
169
|
+
above the questions on a writable board they were three commands you never need
|
|
170
|
+
in the place the eye lands first. They now sit behind "Answer from the terminal
|
|
171
|
+
instead", and open themselves on the boards where they are the answer, decided
|
|
172
|
+
by the `writable` flag the settings fetch already returned.
|
|
173
|
+
|
|
174
|
+
Documented on both surfaces, including the difference the page never explained:
|
|
175
|
+
a **default** is what happens if you say nothing (blank is recorded verbatim as
|
|
176
|
+
your decision), a **recommendation** is what the asking agent thinks you should
|
|
177
|
+
do (it fills the box and submits nothing).
|
|
178
|
+
|
|
179
|
+
## 0.1.41 — 2026-08-18
|
|
180
|
+
|
|
181
|
+
### The knowledge store can now shrink, and nothing is destroyed to do it
|
|
182
|
+
|
|
183
|
+
`.tyran/knowledge/` only ever grew. `knowledge.mjs audit` measured the damage
|
|
184
|
+
and said, in its own output, that nothing merges overlapping entries — true
|
|
185
|
+
since 0.1.35 corrected the three surfaces that had promised otherwise.
|
|
186
|
+
|
|
187
|
+
The producer everyone was waiting for turned out to be the wrong thing to
|
|
188
|
+
build. **`supersedes` was already in the schema, already documented, and read
|
|
189
|
+
by nothing.** Making `selectEntries` honour it turns a merge into an *append*:
|
|
190
|
+
write the entry that states the fact once, name the ones it replaces, touch
|
|
191
|
+
nothing else. The replaced entries stop reaching briefs immediately and keep
|
|
192
|
+
their bytes, their provenance and the counters they earned over months —
|
|
193
|
+
because no file holding them was edited.
|
|
194
|
+
|
|
195
|
+
That shape is the whole safety argument, and it is why no verifier shipped
|
|
196
|
+
alongside. A bad merge is not a lost history to be prevented by review; it is
|
|
197
|
+
one file to delete, after which every retired entry comes back whole.
|
|
198
|
+
Conservation checks — counters summed, provenance carried across — guard a
|
|
199
|
+
*lossy* merge that appending does not perform, and they cannot express the
|
|
200
|
+
risk that actually exists: the merged sentence dropping the important half.
|
|
201
|
+
Certifying the arithmetic while the meaning evaporates is the expensive kind
|
|
202
|
+
of false assurance.
|
|
203
|
+
|
|
204
|
+
**`supersedes` had to widen to a list first**, and that is probably why nothing
|
|
205
|
+
was ever built on it: as a scalar, a merged entry could retire exactly one
|
|
206
|
+
predecessor, so an N→1 merge — which is what consolidation *is* — could not be
|
|
207
|
+
written down at all. An entry may not supersede itself (the validator refuses
|
|
208
|
+
it; a flat suppression set would otherwise hide the entry carrying the
|
|
209
|
+
reference), and a mutually superseding pair hides both, so `audit` names those
|
|
210
|
+
rather than teaching the selector graph theory.
|
|
211
|
+
|
|
212
|
+
**No script decides which entries say the same thing.** That is a judgement and
|
|
213
|
+
it stays the retrospective's — text-similarity scoring was considered and cut,
|
|
214
|
+
because on a store this size the agent adjudicating the candidates reads them
|
|
215
|
+
better than a token score dominated by shared vocabulary. The line that fell
|
|
216
|
+
out is worth keeping: *a script may count a judgement already recorded; it may
|
|
217
|
+
not perform one.*
|
|
218
|
+
|
|
219
|
+
Which is what licensed the other half. `used`/`helpful`/`outdated_reports` are
|
|
220
|
+
report verdicts — recorded judgements — and three surfaces already instructed
|
|
221
|
+
an agent to retire entries on their evidence while **nothing computed it**: the
|
|
222
|
+
same unimplemented-promise defect as 0.1.35, one field over. `audit` now names
|
|
223
|
+
the candidates: reported wrong more often than helpful, or delivered three
|
|
224
|
+
times or more and never once helpful. An entry delivered *once* is never a
|
|
225
|
+
candidate; that is absence of evidence, not evidence.
|
|
226
|
+
|
|
227
|
+
The most useful line it prints is the degenerate one. The counters are
|
|
228
|
+
maintained only by a model hand-editing YAML at retro close, so if that fold is
|
|
229
|
+
not happening every entry reads `helpful: 0` and the rule would flag the entire
|
|
230
|
+
store — confidently, on nothing. A store with no counter evidence now reports
|
|
231
|
+
**that** instead, and flags nothing. Evidence is asked of the whole store
|
|
232
|
+
rather than the live part, or consolidating the one counter-bearing entry away
|
|
233
|
+
would flip the report to "the fold is not happening" — a strong claim, and
|
|
234
|
+
false.
|
|
235
|
+
|
|
236
|
+
Also: a duplicate entry id **across two files** went undetected, because the
|
|
237
|
+
validator allocates its id set per document and runs per file. It matters more
|
|
238
|
+
now that `supersedes` names an id — an ambiguous one retires whichever entry
|
|
239
|
+
the loop reached first. `loadEntries` refuses it through the channel `brief`
|
|
240
|
+
and `audit` already treat as loud.
|
|
241
|
+
|
|
242
|
+
That refusal is why it also earns a doctor finding, `knowledge-duplicate-id`
|
|
243
|
+
(error). The intent had been to add none — an overlap or staleness backlog is
|
|
244
|
+
a judgement queue rather than a malfunction, and would be red on every mature
|
|
245
|
+
store forever, which is the shape people learn to skip. A duplicate id is the
|
|
246
|
+
opposite: never red on a healthy store, and a genuine break. Without it doctor
|
|
247
|
+
reported a **healthy** repo whose every handoff got no brief at all, since
|
|
248
|
+
`brief` exits 1 on a store that does not validate. A gate that cannot fire is
|
|
249
|
+
the thing `doctor --state` exists to catch, so it could hardly be the thing it
|
|
250
|
+
stayed quiet about.
|
|
251
|
+
|
|
252
|
+
`doctor --state` counts live and superseded separately; pairing a
|
|
253
|
+
live-only reachability with an on-disk total would have printed "1 of 3 can
|
|
254
|
+
reach a brief; 0 cannot".
|
|
255
|
+
|
|
256
|
+
Both guard tests from 0.1.35 were **retuned, not removed**. The one banning
|
|
257
|
+
`/consolidat/i` from the audit was a proxy that expires the moment the step
|
|
258
|
+
exists, so it now asserts the property directly: the audit may describe the
|
|
259
|
+
mechanism only while a brief genuinely stops delivering a superseded entry —
|
|
260
|
+
checked by running a brief, not by grepping for a function name. The one
|
|
261
|
+
gating doc prose on an unimplemented feature had an escape hatch by design;
|
|
262
|
+
letting it fall silent would have traded a real guard for none, so it now
|
|
263
|
+
asserts the two self-improvement surfaces agree line for line. The original
|
|
264
|
+
defect was never that the claim existed — it was that one claim lived in three
|
|
265
|
+
places and drifted.
|
|
266
|
+
|
|
267
|
+
### A finding names the command behind it, not a sentence about one
|
|
268
|
+
|
|
269
|
+
A `finding` carried `claim` + `proof`, and `proof` is prose — so the journal
|
|
270
|
+
recorded *"the parser rejects block scalars"* rather than anything the parser
|
|
271
|
+
did. That is a claim standing where evidence should be, which is the thing the
|
|
272
|
+
evidence gate already refuses in an implementer's report. Findings had a pass
|
|
273
|
+
on the same rule.
|
|
274
|
+
|
|
275
|
+
`finding` events now take **`command`** and **`exit_code`**. Both optional,
|
|
276
|
+
both projected into `STATE.md`'s Findings table.
|
|
277
|
+
|
|
278
|
+
**The ask was for the raw OUTPUT, and that was the expensive framing.** Three
|
|
279
|
+
things changed the answer. A stored output is a snapshot that rots and can
|
|
280
|
+
never be re-checked, while a command can be re-run by anyone who doubts the
|
|
281
|
+
claim. What the ask actually wanted was proof that a command ran at all —
|
|
282
|
+
which is the command and its exit code, not the bytes; on a long command the
|
|
283
|
+
bytes are noise. And the payload-size objection that made this an S–M turned
|
|
284
|
+
out not to exist: the cross board already carries findings as a **count**, and
|
|
285
|
+
the per-initiative `board.json` carries none. **Neither byte-compared artefact
|
|
286
|
+
changed** — verified by the goldens, where `BOARD.md` and `board.json` came
|
|
287
|
+
back byte-identical and only `STATE.md` moved. A test now states that rule for
|
|
288
|
+
`command` too, because it is the one field somebody will be tempted to promote
|
|
289
|
+
onto a card.
|
|
290
|
+
|
|
291
|
+
`command` is capped at **500** codepoints, an order of magnitude tighter than
|
|
292
|
+
the prose keys, and the number is measured rather than picked: this repo
|
|
293
|
+
documents 86 shell commands, median 74 codepoints, longest 123. Wide enough
|
|
294
|
+
for any real pipeline; too narrow to smuggle pasted output into a committed
|
|
295
|
+
file. Rejected at append, never truncated, like every other capped key.
|
|
296
|
+
|
|
297
|
+
The prompts had already got ahead of the schema — `agents/implementer.md`
|
|
298
|
+
tells an implementer to journal each dead hypothesis *"with the command output
|
|
299
|
+
that killed it"*, and `tyran:verifier`'s entire report is `command · exit code
|
|
300
|
+
· counts`. There was nowhere structured for either to land, so it went into
|
|
301
|
+
`proof` as prose. Now it has a home, and the implementer, verifier, scout,
|
|
302
|
+
reviewer and conductor prompts say so in one sentence each.
|
|
303
|
+
|
|
304
|
+
**What this does NOT do.** It does not tell a real command from an invented
|
|
305
|
+
one. A recorded command is still the agent's word — the same limit the
|
|
306
|
+
evidence gate prints about itself: *it blocks silence, not forgery.* What
|
|
307
|
+
changes is that the word is now specific and re-runnable instead of prose.
|
|
308
|
+
Verifying a command against the platform's own transcript is designed and
|
|
309
|
+
deliberately unbuilt; `NOTES-REQUESTS.md` §12.3 records the mechanism so it is
|
|
310
|
+
not re-derived.
|
|
311
|
+
|
|
312
|
+
Doctor gains **`finding-no-command`** (info): findings whose proof is prose
|
|
313
|
+
alone, counted and named. Info and not warning because every finding written
|
|
314
|
+
before this release predates the keys, and a check that goes red on upgrade
|
|
315
|
+
day is one people learn to skip. It is never a refusal — `journal.mjs` still
|
|
316
|
+
requires only `area` + `claim`, and a finding from reading code legitimately
|
|
317
|
+
has no command.
|
|
318
|
+
|
|
3
319
|
## 0.1.40 — 2026-08-17
|
|
4
320
|
|
|
5
321
|
### Every session pays for these sentences, so they got shorter
|
package/README.md
CHANGED
|
@@ -57,7 +57,10 @@ asking you to describe it. After every initiative the team runs a retrospective
|
|
|
57
57
|
on itself, and what it changes is Tyran, never your product code. The same
|
|
58
58
|
failure three times becomes knowledge pasted into every matching handoff; five
|
|
59
59
|
times and it becomes a rule in your `CLAUDE.md`, carrying the dates that earned
|
|
60
|
-
it.
|
|
60
|
+
it. That knowledge does not only grow: entries the counters have written off
|
|
61
|
+
are retired on evidence, and two that say one thing are merged by appending a
|
|
62
|
+
third that supersedes both — the originals stay on disk, so an unwanted merge
|
|
63
|
+
is one file to delete. Most retros correctly change nothing.
|
|
61
64
|
|
|
62
65
|
All of it lands on one page — a **board**: what every agent is doing right now,
|
|
63
66
|
which questions are waiting on you (answer them there and the run carries on),
|
|
@@ -188,6 +191,13 @@ It checks Node, installs the plugin, installs the secrets scanner the write
|
|
|
188
191
|
gate needs, and prints the prompt to paste after you restart — which runs
|
|
189
192
|
setup and opens the dashboard in your browser.
|
|
190
193
|
|
|
194
|
+
Tyran refuses some things by default — reading a `.env`, writing outside the
|
|
195
|
+
repository, pushing past your autonomy class. If you would rather it did not,
|
|
196
|
+
`boundaries: {preset: open}` in `.tyran/config.yaml` relaxes all five at once,
|
|
197
|
+
and the dashboard's Settings tab has the switch. Secret scanning at commit and
|
|
198
|
+
push is not one of the five and cannot be turned off from there. See
|
|
199
|
+
[configuration](https://jjanczur.github.io/tyran/configuration/).
|
|
200
|
+
|
|
191
201
|
Or do it by hand, inside Claude Code:
|
|
192
202
|
|
|
193
203
|
```text
|
|
@@ -319,7 +329,7 @@ enforces the cap (3868 of 5000 characters). What each one assumes, when it
|
|
|
319
329
|
fires and who invokes it, is in
|
|
320
330
|
[skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
|
|
321
331
|
themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
|
|
322
|
-
it:
|
|
332
|
+
it: 1646 unit tests, run with `node --test "tests/**/*.test.mjs"`.
|
|
323
333
|
|
|
324
334
|
## Documentation
|
|
325
335
|
|
|
@@ -331,7 +341,7 @@ Everything below also reads as a site, with search and rendered diagrams:
|
|
|
331
341
|
| [Getting started](https://jjanczur.github.io/tyran/getting-started/) | install, first run, the command line, updating |
|
|
332
342
|
| [Architecture](https://jjanczur.github.io/tyran/architecture/) | the four failures, the three layers, the hooks, the principles, the roadmap |
|
|
333
343
|
| [Skills and agents](https://jjanczur.github.io/tyran/skills/) · [the roster](https://jjanczur.github.io/tyran/agents/) | what each one assumes and who invokes it; the tier and effort table, the `.tyran/STOP` brake |
|
|
334
|
-
| [Configuration](https://jjanczur.github.io/tyran/configuration/) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes |
|
|
344
|
+
| [Configuration](https://jjanczur.github.io/tyran/configuration/) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes, `boundaries:` |
|
|
335
345
|
| [Self-improvement](https://jjanczur.github.io/tyran/self-improvement/) | how Tyran learns your repo, and its guardrails |
|
|
336
346
|
| [Journal](https://jjanczur.github.io/tyran/journal/) · [projections](https://jjanczur.github.io/tyran/projections/) | the append-only event schema, and what is generated from it |
|
|
337
347
|
| [The board](https://jjanczur.github.io/tyran/board/) · [the spend ledger](https://jjanczur.github.io/tyran/cost/) | lanes, answering a question, and what a run cost |
|
package/agents/implementer.md
CHANGED
|
@@ -38,7 +38,9 @@ commits and anything written to disk are in English.**
|
|
|
38
38
|
thing you are about to write; if it exists, report it as a corrected
|
|
39
39
|
premise instead of duplicating it. Durable discoveries worth another
|
|
40
40
|
agent's time go into the journal as `finding` events (`area` + `claim`
|
|
41
|
-
are required, plus its `proof`) — not only into prose.
|
|
41
|
+
are required, plus its `proof`) — not only into prose. When you found it
|
|
42
|
+
by RUNNING something, add `command` and `exit_code`: a command the next
|
|
43
|
+
agent can re-run outlives a sentence about what you saw.
|
|
42
44
|
- **Verify the handoff's premises in the code.** A stale path, a wrong
|
|
43
45
|
assignment, a function that no longer exists — correct it and report the
|
|
44
46
|
correction EXPLICITLY instead of executing blindly. Premises about DATA
|
|
@@ -59,7 +61,8 @@ commits and anything written to disk are in English.**
|
|
|
59
61
|
- **Two refuted hypotheses is the timebox.** When two named root-cause
|
|
60
62
|
hypotheses have both been disproven and you do not have a third, stop:
|
|
61
63
|
signal `blocked`, write what you RULED OUT into the journal as a
|
|
62
|
-
`finding` — each dead hypothesis with the command
|
|
64
|
+
`finding` — each dead hypothesis with the `command` that killed it and its
|
|
65
|
+
`exit_code`, the output itself in your report —
|
|
63
66
|
and report back. The ruled-out list IS the deliverable: the conductor
|
|
64
67
|
re-routes the story with more reasoning or a stronger tier, and that
|
|
65
68
|
agent starts where you stopped instead of at the wall. Handing back
|
package/agents/retro.md
CHANGED
|
@@ -73,12 +73,15 @@ next retro relitigating the same idea.
|
|
|
73
73
|
report generators. A one-off harness from an initiative either becomes a
|
|
74
74
|
general tool or gets deleted; do not leave dead files behind.
|
|
75
75
|
- **Knowledge upkeep:** fold the reports' knowledge-brief verdicts into the
|
|
76
|
-
entries' counters
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
counters
|
|
81
|
-
satisfies the deletion preference.
|
|
76
|
+
entries' counters, consolidate what the store now says twice, and retire or
|
|
77
|
+
split entries `doctor --state` flags as `knowledge-entry-oversized` (all
|
|
78
|
+
three procedures live in `skills/retro/SKILL.md`, under "Write down what is
|
|
79
|
+
true about THIS repo" — one home, not two). `knowledge.mjs audit` names the
|
|
80
|
+
entries whose counters have written them off, and consolidating is merging
|
|
81
|
+
what you judge to be one fact — which satisfies the deletion preference.
|
|
82
|
+
Consolidation APPENDS an entry whose `supersedes:` names the ones it
|
|
83
|
+
replaces; you never edit or delete the originals, so a merge you got wrong
|
|
84
|
+
costs one deleted file rather than counters earned over months.
|
|
82
85
|
- **The mistakes ledger:** append an entry to `MISTAKES.md` for every breakage
|
|
83
86
|
this initiative actually paid for — what happened, the root cause, the
|
|
84
87
|
consequence, the prevention — and give it a **signature** you reuse for the
|
package/agents/reviewer.md
CHANGED
|
@@ -63,7 +63,9 @@ sentence is a claim about evidence.
|
|
|
63
63
|
2. **Run your OWN verification.** Do not believe the author's report — an
|
|
64
64
|
author's report with no raw command output you reject on sight, without
|
|
65
65
|
reading further. Run the tests yourself; for UI, drive the browser yourself
|
|
66
|
-
through `browser-check`. Paste what you got, with counts.
|
|
66
|
+
through `browser-check`. Paste what you got, with counts. A `finding` you
|
|
67
|
+
journal carries the `command` and `exit_code` behind it, so the next reader
|
|
68
|
+
re-runs your evidence instead of trusting your sentence about it.
|
|
67
69
|
- **Signal ONLY a blockage that genuinely stops the review** — a `progress`
|
|
68
70
|
event with `state: "blocked"` (then `"unblocked"`) to the main checkout's
|
|
69
71
|
journal, path from the handoff. Nothing else: your lease IS your
|
package/agents/scout.md
CHANGED
|
@@ -15,7 +15,8 @@ disk is in English.**
|
|
|
15
15
|
side effect?" as a question you must be able to answer yes to before
|
|
16
16
|
running it.
|
|
17
17
|
2. **A finding is a claim plus its proof.** Every line you return is
|
|
18
|
-
`finding -> path:line, quoted fragment, or
|
|
18
|
+
`finding -> path:line, quoted fragment, URL, or the command you ran and what
|
|
19
|
+
it exited with`. The conductor reads dozens
|
|
19
20
|
of these; there is no budget for warm-up paragraphs, and an unsourced
|
|
20
21
|
finding costs more than no finding because someone will act on it. Prefix
|
|
21
22
|
the ones that will outlive this task with `DURABLE:` — the conductor
|
package/agents/verifier.md
CHANGED
|
@@ -14,7 +14,8 @@ disk is in English — though you should not be writing anything to disk.**
|
|
|
14
14
|
|
|
15
15
|
1. **Run EXACTLY the commands the handoff names, in order.** No substitutes,
|
|
16
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
|
|
17
|
+
repo is a finding to report, never a thing to install — journalled with the
|
|
18
|
+
`command` you were handed and the `exit_code` you got.
|
|
18
19
|
- Take the heavy-slot lease first when the handoff names one — a test
|
|
19
20
|
suite is a heavy phase — and release it when you finish, including when
|
|
20
21
|
you finish by failing.
|
package/bin/tyran.mjs
CHANGED
|
@@ -78,7 +78,7 @@ export const COMMANDS = {
|
|
|
78
78
|
],
|
|
79
79
|
knowledge: [
|
|
80
80
|
'knowledge.mjs',
|
|
81
|
-
'
|
|
81
|
+
'Brief the knowledge entries that apply to a set of paths, or audit the store for what no brief can reach.',
|
|
82
82
|
],
|
|
83
83
|
mistakes: [
|
|
84
84
|
'mistakes.mjs',
|
|
@@ -112,7 +112,12 @@ did not object to would be quietly approving the whole session. `deny` from
|
|
|
112
112
|
any hook wins over `allow` from another, but that is no comfort when ours is
|
|
113
113
|
the only hook.
|
|
114
114
|
|
|
115
|
-
|
|
115
|
+
"No objection" is `{}`, and it always will be. Since 0.1.43 the runtime CAN
|
|
116
|
+
emit `allow`, from `allowPayload`, reached only by a handler returning
|
|
117
|
+
`{decision: 'allow'}` on purpose — the policy gate does so when a repo sets
|
|
118
|
+
`boundaries.prompts: skip`. No failure path reaches it: a throw, a timeout, an
|
|
119
|
+
overrun budget, a malformed input and an unrecognised verdict are all still
|
|
120
|
+
refusals. The sentence above is why that distinction is the whole design.
|
|
116
121
|
|
|
117
122
|
## 5. Matcher syntax — one predicate for every event
|
|
118
123
|
|
|
@@ -210,6 +210,43 @@ export function askPayload(event, reason) {
|
|
|
210
210
|
};
|
|
211
211
|
}
|
|
212
212
|
|
|
213
|
+
/**
|
|
214
|
+
* The allow payload for `event` — an explicit AUTO-APPROVAL.
|
|
215
|
+
*
|
|
216
|
+
* This is the one output in this file that makes a tool call happen without
|
|
217
|
+
* the platform asking anybody. It exists because an operator asked for exactly
|
|
218
|
+
* that and set `boundaries.prompts: skip` in their own config, and it is
|
|
219
|
+
* reachable ONLY from a handler that returns `{decision: 'allow'}` on purpose.
|
|
220
|
+
*
|
|
221
|
+
* Read the invariant carefully, because it is narrower than it looks and the
|
|
222
|
+
* narrowness is the whole safety argument: NO failure mode reaches this
|
|
223
|
+
* function. A throw, a timeout, a malformed input, an unrecognised return
|
|
224
|
+
* value and an overrun budget all still become refusals, exactly as before.
|
|
225
|
+
* What changed is that "allow" is now SAYABLE, not that anything says it by
|
|
226
|
+
* accident — which is the property `PASS` below is about.
|
|
227
|
+
*
|
|
228
|
+
* A refusal from any other hook still wins: `deny` beats `allow` across
|
|
229
|
+
* hooks (measured — HOOK-CONTRACT-MEASURED.md §4). So this cannot approve a
|
|
230
|
+
* command the secrets gate refuses, and that is not politeness between gates,
|
|
231
|
+
* it is the platform's own precedence.
|
|
232
|
+
*/
|
|
233
|
+
export function allowPayload(event, reason) {
|
|
234
|
+
const meta = EVENTS[event];
|
|
235
|
+
if (meta === undefined || meta.refusal === null) {
|
|
236
|
+
throw new GateOnProbeEventError(String(event));
|
|
237
|
+
}
|
|
238
|
+
if (meta.refusal !== 'permissionDecision') {
|
|
239
|
+
throw new Error(`"allow" is only expressible where the platform models permissionDecision, not on ${String(event)}`);
|
|
240
|
+
}
|
|
241
|
+
return {
|
|
242
|
+
hookSpecificOutput: {
|
|
243
|
+
hookEventName: event,
|
|
244
|
+
permissionDecision: 'allow',
|
|
245
|
+
permissionDecisionReason: reason,
|
|
246
|
+
},
|
|
247
|
+
};
|
|
248
|
+
}
|
|
249
|
+
|
|
213
250
|
/** The context-injection payload for `event`, or `{}` where it accepts none. */
|
|
214
251
|
export function contextPayload(event, additionalContext) {
|
|
215
252
|
const meta = EVENTS[event];
|
|
@@ -225,8 +262,16 @@ export function contextPayload(event, additionalContext) {
|
|
|
225
262
|
* gate is satisfied", it means "approve this tool call and skip the
|
|
226
263
|
* permission prompt". A gate whose only job is to look for secrets would
|
|
227
264
|
* then be silently auto-approving every command it happened not to object
|
|
228
|
-
* to.
|
|
229
|
-
*
|
|
265
|
+
* to.
|
|
266
|
+
*
|
|
267
|
+
* `allowPayload` above CAN emit it, and the distinction between the two is
|
|
268
|
+
* the safety property, so state it as a rule rather than as a fact about
|
|
269
|
+
* today's callers: **`PASS` never becomes `allow`, and no failure mode ever
|
|
270
|
+
* does.** Auto-approval requires a handler to return `{decision: 'allow'}`
|
|
271
|
+
* deliberately, which one gate does only when an operator wrote
|
|
272
|
+
* `boundaries.prompts: skip` in their own config. Tests pin both halves —
|
|
273
|
+
* that PASS emits `{}`, and that a throw, a timeout, a malformed input and an
|
|
274
|
+
* unrecognised return value all still refuse.
|
|
230
275
|
*/
|
|
231
276
|
export const PASS = Object.freeze({ decision: 'pass' });
|
|
232
277
|
|
|
@@ -486,11 +531,13 @@ function refusalText({ errorClass, message, fix }) {
|
|
|
486
531
|
* platform's timeout kills the process and DISCARDS its output, so a
|
|
487
532
|
* gate that is merely slow is a gate that approves.
|
|
488
533
|
*
|
|
489
|
-
* `handler(input)` returns `PASS`, `{ decision: 'deny', reason }` or —
|
|
490
|
-
*
|
|
491
|
-
*
|
|
492
|
-
*
|
|
493
|
-
*
|
|
534
|
+
* `handler(input)` returns `PASS`, `{ decision: 'deny', reason }` or — on
|
|
535
|
+
* events that model permissionDecision — `{ decision: 'ask', reason }`, which
|
|
536
|
+
* renders the user's own prompt for exactly this call, or
|
|
537
|
+
* `{ decision: 'allow', reason }`, which AUTO-APPROVES it and skips that
|
|
538
|
+
* prompt. Anything else is treated as a bug and refuses — an unrecognised
|
|
539
|
+
* return value must not be able to mean "allow", which is why allow has to be
|
|
540
|
+
* spelled out and cannot be arrived at.
|
|
494
541
|
*
|
|
495
542
|
* ## What the deadline does and does not promise
|
|
496
543
|
*
|
|
@@ -721,8 +768,19 @@ export async function runGate({ event, handler, deadlineMs, io = defaultIo() })
|
|
|
721
768
|
emit(payload);
|
|
722
769
|
return;
|
|
723
770
|
}
|
|
771
|
+
if (verdict !== null && typeof verdict === 'object' && verdict.decision === 'allow') {
|
|
772
|
+
// Deliberate auto-approval. Reached only from an explicit handler
|
|
773
|
+
// return; every ending that is not one — throw, timeout, overrun,
|
|
774
|
+
// malformed input, unrecognised verdict — is still a refusal.
|
|
775
|
+
const { payload } = clampPayload(
|
|
776
|
+
(reason) => allowPayload(outEvent, reason),
|
|
777
|
+
sanitizeForOutput(String(verdict.reason ?? 'allowed without a stated reason')),
|
|
778
|
+
);
|
|
779
|
+
emit(payload);
|
|
780
|
+
return;
|
|
781
|
+
}
|
|
724
782
|
throw new Error(
|
|
725
|
-
`handler returned ${JSON.stringify(verdict)}; expected PASS or { decision: 'deny' | 'ask', reason }`,
|
|
783
|
+
`handler returned ${JSON.stringify(verdict)}; expected PASS or { decision: 'deny' | 'ask' | 'allow', reason }`,
|
|
726
784
|
);
|
|
727
785
|
} catch (err) {
|
|
728
786
|
refuse(outEvent, describeError(err));
|