@jjanczur/tyran 0.1.43 → 0.1.44

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.
@@ -87,6 +87,11 @@ export const GROUPS = Object.freeze([
87
87
  path: ['profile'],
88
88
  label: 'Cost profile',
89
89
  help: 'How much verification each piece of work carries. The cheaper profiles skip review passes, not tests.',
90
+ explain: {
91
+ what: 'How many independent eyes look at a piece of work before it counts as done.',
92
+ changes: 'The number of review passes and agents the conductor spends per ticket — never whether tests run; those always do.',
93
+ effect: 'Eco finishes sooner and cheaper with tests as the only guard; full adds an independent review and the strongest tier on risky work, so mistakes are caught before you see them.',
94
+ },
90
95
  ...choice(PROFILES, {
91
96
  eco: 'Fewest agents and fewest review passes. Good for small, well-understood changes.',
92
97
  balanced: 'The default. Implementation plus an independent review on anything non-trivial.',
@@ -98,6 +103,11 @@ export const GROUPS = Object.freeze([
98
103
  path: ['autonomy'],
99
104
  label: 'Deployment autonomy',
100
105
  help: 'How far a finished piece of work may travel without you. The gate enforces this downward — it will not stop someone who edits this file from raising it, which is why the policy below decides who may.',
106
+ explain: {
107
+ what: 'The furthest a finished change may travel without a human touching it.',
108
+ changes: 'Which git pushes the gate allows: P1 stops at a feature branch, P2 reaches staging, P3 may land the default branch.',
109
+ effect: 'At P1 you merge every PR yourself; at P3 Tyran can finish a story end to end. Irreversible pushes — force, mirror, remote deletes — are refused at every level, including P3.',
110
+ },
101
111
  widening: {
102
112
  scale: 'autonomy',
103
113
  consequence:
@@ -122,6 +132,11 @@ export const GROUPS = Object.freeze([
122
132
  path: ['boundaries', 'preset'],
123
133
  label: 'Preset',
124
134
  help: 'The one switch. "Open" turns every boundary below to its loose setting at once — the closest thing Tyran has to running Claude Code with permissions skipped. Anything you set individually below wins over the preset.',
135
+ explain: {
136
+ what: 'The master position for every boundary in this group at once.',
137
+ changes: 'Flips outside-repo access, credential reads, your path rules, push checks and permission prompts together; any boundary you set individually below overrides it.',
138
+ effect: 'On "open", agents move without friction and without asking — the four things no setting reaches (secret scanning, the hooks, their registry, the STOP brake) still hold.',
139
+ },
125
140
  widening: {
126
141
  scale: 'preset',
127
142
  consequence:
@@ -137,6 +152,11 @@ export const GROUPS = Object.freeze([
137
152
  path: ['boundaries', 'outside_repo'],
138
153
  label: 'Files outside this repository',
139
154
  help: 'Today a path outside the repo root is refused for every agent. Allowing it lets them read and write anywhere on this machine — another project, your home directory, system files.',
155
+ explain: {
156
+ what: 'Whether an agent may touch any file that lives outside this repository’s root.',
157
+ changes: 'On "refuse", every read and write outside the repo is denied for every agent; on "allow", the whole machine is in reach.',
158
+ effect: 'The strictest boundary Tyran has: it is what makes "an agent went wrong" mean "inside this repo, revertable with git" rather than "anywhere on this computer".',
159
+ },
140
160
  widening: {
141
161
  scale: 'boundary',
142
162
  consequence: 'Agents will be able to write files anywhere on this machine, not only inside this repository.',
@@ -151,6 +171,11 @@ export const GROUPS = Object.freeze([
151
171
  path: ['boundaries', 'credentials'],
152
172
  label: 'Credential files',
153
173
  help: 'Today .env files, private keys, ~/.ssh, ~/.aws and their relatives are refused before they can reach the model — a transcript is storage. Allowing it also removes the false refusal where a word merely ENDING in .key or .pem is treated as a file.',
174
+ explain: {
175
+ what: 'Whether credential-shaped files — .env, private keys, ~/.ssh, ~/.aws — may be read into the conversation at all.',
176
+ changes: 'On "refuse" they are blocked before the model sees a byte; on "allow" agents can read them like any other file.',
177
+ effect: 'A transcript is storage, so a secret read once is a secret retained. What stops secrets being COMMITTED stays separate — the commit/push scan runs whatever this says.',
178
+ },
154
179
  widening: {
155
180
  scale: 'boundary',
156
181
  consequence:
@@ -166,6 +191,11 @@ export const GROUPS = Object.freeze([
166
191
  path: ['boundaries', 'path_classes'],
167
192
  label: 'Your own path rules',
168
193
  help: 'The AUTO / GATED / KERNEL rules in the policy below. Allowing this makes them advisory: a subagent may write a path you gated. The four paths that protect the gate itself stay refused whatever this says.',
194
+ explain: {
195
+ what: 'Whether the AUTO / GATED / KERNEL classes in the autonomy policy further down this page are enforced on writes.',
196
+ changes: 'On "allow" they become advisory: a subagent may write a path you gated, and only the four self-protecting paths still refuse.',
197
+ effect: 'Turning this off removes the distinction the policy exists to draw — everything an agent can reach becomes effectively AUTO.',
198
+ },
169
199
  widening: {
170
200
  scale: 'boundary',
171
201
  consequence: 'The GATED and KERNEL rules in your own policy stop being enforced for writes.',
@@ -180,6 +210,11 @@ export const GROUPS = Object.freeze([
180
210
  path: ['boundaries', 'push'],
181
211
  label: 'Where work may be pushed',
182
212
  help: 'Turns off the deployment-class check on git push entirely, including the rules that gate the pushes nothing can undo — a force push to main, a deleted remote branch, a mirror push.',
213
+ explain: {
214
+ what: 'Whether git pushes are checked against the deployment autonomy above at all.',
215
+ changes: 'On "allow", the branch rules AND the irreversible-operation rules stop applying — force pushes, mirror pushes and remote branch deletes included.',
216
+ effect: 'This is the only setting that can permit an operation git cannot undo. The deployment-autonomy dropdown above becomes decoration while this is loose.',
217
+ },
183
218
  widening: {
184
219
  scale: 'boundary',
185
220
  consequence:
@@ -195,6 +230,11 @@ export const GROUPS = Object.freeze([
195
230
  path: ['boundaries', 'prompts'],
196
231
  label: 'Permission prompts',
197
232
  help: 'Whether Claude Code still asks you before a tool call this gate has no objection to. "Skip" auto-approves those calls, which is what people mean by skipping permissions — a refusal from any gate still wins, so this cannot approve something another gate denied.',
233
+ explain: {
234
+ what: 'Whether Claude Code still shows its own permission dialog for calls this gate has already looked at and passed.',
235
+ changes: 'On "skip", those calls are auto-approved and the session flows without interruptions; refusals from any gate still refuse.',
236
+ effect: 'Pure convenience versus oversight: nothing becomes allowed that was not already, you just stop being the click between an allowed call and its execution.',
237
+ },
198
238
  widening: {
199
239
  scale: 'prompts',
200
240
  consequence: 'Claude Code will stop asking before it edits files or runs commands that no gate objects to.',
@@ -222,6 +262,16 @@ export const GROUPS = Object.freeze([
222
262
  deep: 'Root-cause diagnosis, hard implementation, risky review — where a wrong answer is expensive.',
223
263
  top: 'Security review, arbitration, final acceptance. The last word, used sparingly.',
224
264
  }[key],
265
+ explain: {
266
+ what: `The model id every agent spawned at the "${key}" tier runs on.`,
267
+ changes: 'Only which model answers when a skill or agent asks for this tier — roles and routing stay as they are.',
268
+ effect: {
269
+ cheap: 'A stronger model here buys nothing but cost: this tier exists for work where any competent model gives the same answer.',
270
+ work: 'This is most of your spend and most of your quality — the tier to adjust first when either is wrong.',
271
+ deep: 'Skimping here is where wrong answers get expensive: this tier is called exactly when the work is known to be hard.',
272
+ top: 'The tier trusted with the final word — used rarely enough that a strong model here costs little and vetoes a lot.',
273
+ }[key],
274
+ },
225
275
  placeholder: 'a model id or alias your CLI accepts',
226
276
  })),
227
277
  },
@@ -236,6 +286,11 @@ export const GROUPS = Object.freeze([
236
286
  label: 'Validation commands',
237
287
  kind: 'list',
238
288
  help: 'Run in order before any work is reported. Each must EXIT — a watch-mode test runner here hangs every agent you ever spawn, which is a real measured incident, not a hypothetical.',
289
+ explain: {
290
+ what: 'The commands that define "done" in this repository — every agent runs them before reporting any work.',
291
+ changes: 'What proof each ticket must carry: add a linter and every future ticket lints; remove the tests and nothing runs them.',
292
+ effect: 'This list is Tyran’s definition of working code. A command that never exits (watch mode) hangs every agent; a missing one means work ships unproven.',
293
+ },
239
294
  placeholder: 'npm test',
240
295
  },
241
296
  {
@@ -244,6 +299,11 @@ export const GROUPS = Object.freeze([
244
299
  label: 'Shared zones',
245
300
  kind: 'list',
246
301
  help: 'Files more than one agent may touch in parallel. Writes to these are append-only and serialized by the conductor, so two agents cannot clobber each other.',
302
+ explain: {
303
+ what: 'The files that several parallel agents are expected to touch at once — registries, barrel files, route tables.',
304
+ changes: 'Which paths the conductor serializes: writes there become append-only and take turns instead of racing.',
305
+ effect: 'A hot file missing from this list is the classic parallel-agent failure: two branches both "won" and one agent’s work silently vanished in the merge.',
306
+ },
247
307
  placeholder: 'src/registry.ts',
248
308
  },
249
309
  ],
@@ -264,6 +324,11 @@ export const GROUPS = Object.freeze([
264
324
  pause: 'Winds work down at the threshold, checkpoints it, and schedules the resume.',
265
325
  }),
266
326
  help: 'What happens as the usage window fills up.',
327
+ explain: {
328
+ what: 'Whether Tyran watches your subscription usage windows and acts before they run out.',
329
+ changes: 'Off ignores usage entirely; warn only reports it; pause winds running work down at the threshold, saves a checkpoint and schedules its own resume.',
330
+ effect: 'Pause is what makes overnight runs survivable: work stops at a clean seam instead of mid-edit when the platform cuts the session off.',
331
+ },
267
332
  },
268
333
  {
269
334
  id: 'limits.pause_at_percent',
@@ -274,6 +339,11 @@ export const GROUPS = Object.freeze([
274
339
  max: 100,
275
340
  unit: '%',
276
341
  help: 'How full the five-hour window must be before work winds down. The floor of 50 exists to catch 0.97 pasted where 97 belongs.',
342
+ explain: {
343
+ what: 'The fill level of the rolling five-hour usage window at which a pause begins.',
344
+ changes: 'Lower pauses earlier with margin to spare; higher squeezes more work out of each window at the risk of a hard platform cutoff.',
345
+ effect: 'The margin between this number and 100 is what the wind-down itself gets to spend — checkpointing costs tokens too.',
346
+ },
277
347
  },
278
348
  {
279
349
  id: 'limits.weekly_pause_at_percent',
@@ -284,6 +354,11 @@ export const GROUPS = Object.freeze([
284
354
  max: 100,
285
355
  unit: '%',
286
356
  help: 'The same threshold for the seven-day window. Hitting this one means a much longer wait.',
357
+ explain: {
358
+ what: 'The same pause threshold, for the seven-day usage window.',
359
+ changes: 'When the weekly window — not the five-hour one — is what stops work.',
360
+ effect: 'A weekly pause can mean days, not hours: this threshold decides how much of the week’s budget overnight work may consume before a human re-decides.',
361
+ },
287
362
  },
288
363
  {
289
364
  id: 'limits.wait_max_hours',
@@ -294,6 +369,11 @@ export const GROUPS = Object.freeze([
294
369
  max: 24,
295
370
  unit: 'h',
296
371
  help: 'A reset further away than this is a LONG pause: it gets announced rather than silently waited out. The weekly window can be days.',
372
+ explain: {
373
+ what: 'The longest gap Tyran will wait out silently before treating the pause as a long one.',
374
+ changes: 'Where the line between "quietly resume later" and "tell the operator" sits.',
375
+ effect: 'Below this, a pause is plumbing; above it, it is news — the setting decides which pauses you hear about.',
376
+ },
297
377
  },
298
378
  {
299
379
  id: 'limits.long_wait',
@@ -304,6 +384,11 @@ export const GROUPS = Object.freeze([
304
384
  resume: 'Schedule the resume anyway, however far out it is.',
305
385
  }),
306
386
  help: 'What the scheduler does when the reset is further away than the wait above.',
387
+ explain: {
388
+ what: 'The long-pause policy: hold for a human, or schedule the resume however far out it is.',
389
+ changes: 'Whether a days-away reset ends with Tyran waiting for you, or with Tyran waking itself when the window returns.',
390
+ effect: '"Resume" keeps an overnight programme moving across a weekly pause; "hold" guarantees a human looks at the situation before more budget is spent.',
391
+ },
307
392
  },
308
393
  {
309
394
  id: 'limits.resume_margin_minutes',
@@ -314,6 +399,11 @@ export const GROUPS = Object.freeze([
314
399
  max: 240,
315
400
  unit: 'min',
316
401
  help: 'How long after the window resets before work restarts. A little slack absorbs clock skew between your machine and the platform.',
402
+ explain: {
403
+ what: 'The slack between the platform’s window reset and Tyran restarting work.',
404
+ changes: 'How long after the reset the resume fires.',
405
+ effect: 'Too small and a clock-skewed resume lands before the window actually reset, burning an attempt; the cost of generous is only minutes of idleness.',
406
+ },
317
407
  },
318
408
  {
319
409
  id: 'limits.keep_awake',
@@ -321,6 +411,11 @@ export const GROUPS = Object.freeze([
321
411
  label: 'Hold the machine awake',
322
412
  kind: 'boolean',
323
413
  help: 'A laptop that suspends takes the resume watcher down with it. This holds the SYSTEM awake while it waits — never the display, so your screen lock is untouched.',
414
+ explain: {
415
+ what: 'Whether the machine is held awake while a scheduled resume waits.',
416
+ changes: 'On, the system cannot suspend while the watcher waits (the display still sleeps and locks); off, the laptop may sleep through its own resume.',
417
+ effect: 'The difference between an overnight run that resumed at 3 AM and one you find still paused at breakfast because the lid was closed.',
418
+ },
324
419
  },
325
420
  ],
326
421
  },
@@ -467,6 +562,12 @@ export function readSettings(tyranDir) {
467
562
  id: setting.id,
468
563
  label: setting.label,
469
564
  help: setting.help,
565
+ // The structured explanation the board folds shut under each row:
566
+ // what it is, what changing it does, how it lands on Tyran. The
567
+ // widening consequence travels beside it so the cost of loosening is
568
+ // readable BEFORE the confirm dialog restates it.
569
+ explain: setting.explain ?? null,
570
+ widens: setting.widening?.consequence ?? null,
470
571
  kind: setting.kind ?? 'choice',
471
572
  choices: setting.choices ?? null,
472
573
  min: setting.min ?? null,
@@ -16,8 +16,17 @@
16
16
  #
17
17
  # Validate: node scripts/schema.mjs validate policy .tyran/policies/autonomy.yaml
18
18
 
19
- # Applied when no rule matches. GATED means "ask me" — the safe answer.
20
- default: GATED
19
+ # Applied when no rule matches. AUTO since 0.1.44 (operator-decided
20
+ # 2026-08-19: the shipped defaults were stricter than a new install needs).
21
+ # What this actually reaches is small: the gate is silent outside its
22
+ # governed prefixes (`.tyran/`, `.claude/`, the hooks directory), so this
23
+ # default was never what protected your source tree — it decided only the
24
+ # paths under those prefixes that no rule below names. What it gives up:
25
+ # an UNKNOWN file there — a new state file from a newer Tyran, a stray
26
+ # `.claude/` helper — is now writable by a subagent instead of denied.
27
+ # Every named rule below still applies, the KERNEL floors cannot be edited
28
+ # away, and setting this back to GATED is one word in this file.
29
+ default: AUTO
21
30
 
22
31
  rules:
23
32
  - path: .tyran/knowledge/**
@@ -41,11 +50,15 @@ rules:
41
50
  # 0.1.9 is `.tyran/state/<slug>/locks/`, covered by the `.tyran/state/**`
42
51
  # rule above; `doctor --state` reports a leftover `.tyran/initiatives/`
43
52
  # directory. The measured incident that produced this rule: leases matched
44
- # NO rule, fell through to `default: GATED`, and `verdictForClass(GATED,
45
- # unsupervised)` denies unconditionally — so no implementer in any repo
46
- # could satisfy the take-your-own-lease protocol of iron rule 7, and the
47
- # conductor had to write every lease itself, putting the record of who
48
- # holds a resource in the one place rule 7 says it must not live: the lead.
53
+ # NO rule, fell through to the then-shipped `default: GATED`, and
54
+ # `verdictForClass(GATED, unsupervised)` denies unconditionally — so no
55
+ # implementer in any repo could satisfy the take-your-own-lease protocol of
56
+ # iron rule 7, and the conductor had to write every lease itself, putting
57
+ # the record of who holds a resource in the one place rule 7 says it must
58
+ # not live: the lead. The default is AUTO now, which closes that incident
59
+ # class by itself; the rule stays because an explicit reason beats a
60
+ # fall-through, and because an operator who tightens the default back to
61
+ # GATED must not resurrect the incident.
49
62
  - path: .tyran/initiatives/*/locks/**
50
63
  class: AUTO
51
64
  reason: legacy lease location for installs adopted at <= 0.1.8; GATED denies every subagent unconditionally, which makes the take-your-own-lease protocol of iron rule 7 unsatisfiable
@@ -66,9 +79,16 @@ rules:
66
79
  class: AUTO
67
80
  reason: mostly a description of this repo — validation commands, package manager, shared zones — and an agent that finds it wrong is what is best placed to correct it
68
81
 
82
+ # Was GATED ("overriding a core agent freezes it at the version it was
83
+ # copied from" — still true, still the cost). Relaxed with the default in
84
+ # 0.1.44: GATED denies a subagent unconditionally, so the retro agent —
85
+ # whose whole job includes maintaining these files — could only ever
86
+ # propose. The trade, stated because an unstated cost is a false
87
+ # guarantee: an agent can now freeze or degrade a core agent by writing
88
+ # here; the rollback is a git revert, and the freeze is doctor's to find.
69
89
  - path: .claude/agents/**
70
- class: GATED
71
- reason: overriding a core agent freezes it at the version it was copied from
90
+ class: AUTO
91
+ reason: agent definitions are the material the retro loop maintains; a bad write is one git revert, and an override that freezes a core agent is what doctor reports
72
92
 
73
93
  # Operator-owned prose, loaded into every session in this repository. The
74
94
  # gate is otherwise SILENT at the repo root — the governed prefixes are