@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.
@@ -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.40",
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.40",
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. Most retros correctly change nothing.
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: 1590 unit tests, run with `node --test "tests/**/*.test.mjs"`.
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 |
@@ -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 output that killed it —
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 (the fold procedure lives in `skills/retro/SKILL.md`, under
77
- "Write down what is true about THIS repo" — one home, not two), and retire or
78
- split entries
79
- `doctor --state` flags as `knowledge-entry-oversized`. An entry whose
80
- counters say it stopped earning its keep is a deletion candidate, which
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
@@ -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 URL`. The conductor reads dozens
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
@@ -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
- 'Select the knowledge entries that apply to a set of paths and print a paste-ready brief for a handoff.',
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
- This runtime has no way to emit it. "No objection" is `{}`.
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. There is no way to emit `allow` from this runtime, and a test pins
229
- * that.
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
- * on events that model permissionDecision — `{ decision: 'ask', reason }`,
491
- * which renders the user's own prompt for exactly this call. Anything else
492
- * is treated as a bug and refuses — an unrecognised return value must not
493
- * be able to mean "allow".
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));