@jjanczur/tyran 0.1.0 → 0.1.1

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.0",
14
+ "version": "0.1.1",
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.0",
3
+ "version": "0.1.1",
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,6 +1,90 @@
1
1
  # Changelog
2
2
 
3
- ## 0.1.0 — unreleased
3
+ ## 0.1.1 — 2026-07-29
4
+
5
+ Both entries below come from one install of 0.1.0 on a real repository. The
6
+ version is bumped rather than folded into 0.1.0 because `claude plugin update`
7
+ compares **versions**, not commits: with the manifest left at 0.1.0 it reports
8
+ "already at the latest version" and users never receive the fix.
9
+
10
+ ### `.tyran/config.yaml` is AUTO, and what that costs is written down
11
+
12
+ **The file that says how to validate this repo was one an agent could not
13
+ fix.** Measured on the same install as below: setup inferred `pnpm test`,
14
+ which in that repo is bare `vitest` — watch mode, it never exits, and it would
15
+ have hung every agent handed to it. The session that *discovered* that could
16
+ not repair the file that said it. It produced a diff, then a heredoc for the
17
+ operator to paste, then explained why it would not route around its own gate.
18
+ It was right not to. The gate was wrong.
19
+
20
+ So the shipped policy classes `.tyran/config.yaml` `AUTO`. It is mostly a
21
+ description of the repository — package manager, validation commands, shared
22
+ zones — and the agent that finds it wrong is what is best placed to correct it.
23
+
24
+ The cost is real and is now stated in all four places a user might read
25
+ (`templates/policies/autonomy.yaml`, `docs/configuration.md`,
26
+ `docs/policy-gate.md`, `docs/self-improvement.md`), because an unstated cost is
27
+ a false guarantee: **`autonomy:` lives in this file too, so an agent can raise
28
+ its own deployment class from P1 to P3 and then push to main.** What remains is
29
+ weaker and is said as such — nothing *infers* a raise, and a raise is a diff in
30
+ a committed file with its provenance beside it. Note that `docs/policy-gate.md`
31
+ had already measured this exact escalation happening *under* GATED, in an
32
+ unattended main loop, wherever `Write` is allow-listed; GATED was buying less
33
+ here than it looked like it was buying.
34
+
35
+ The push gate's own refusal named the old class too, and naming a class there
36
+ was the underlying mistake rather than naming the wrong one: the text is
37
+ per-repo configuration, so any class it prints goes stale the moment somebody
38
+ reclassifies the file. It now says the policy decides and names nothing, and
39
+ the test asserts the *absence* of a class claim instead of pinning a string
40
+ that has already been wrong once.
41
+
42
+ Two claims that had gone false are corrected rather than left standing:
43
+ `README.md`'s "the config file holding it is GATED, not KERNEL" and
44
+ `docs/configuration.md`'s "Tyran never raises it on its own — that path is
45
+ blocked by the policy hook". A test now pins the class *and* pins that the
46
+ template still spells out what it gives up, because flipping it back is a
47
+ one-word edit nobody would notice in review.
48
+
49
+ ### Setup no longer locks the repository it is setting up
50
+
51
+ **`/tyran:setup` created `.tyran/config.yaml` and stopped, and that one
52
+ missing file made the repository unwritable.** The policy gate is silent in a
53
+ repo with no `.tyran/` directory and refuses every write in a repo that has
54
+ one without `.tyran/policies/autonomy.yaml` under it. Both halves are right;
55
+ their seam was not. Setup's own first command moved a fresh repo from
56
+ "unmanaged" to "refuses everything" — including the write that would have
57
+ installed the missing policy. Measured on a real install: the session ended
58
+ with the operator being handed a `mkdir` and a `cp` to run by hand, in the
59
+ middle of a one-command setup.
60
+
61
+ `scan-repo.mjs` now installs the policy from the shipped template **before**
62
+ it writes the config, and removes what it created if it cannot, so a failed
63
+ bootstrap cannot leave behind the exact state it exists to prevent. A repo
64
+ from before this change is repaired with `--ensure-policy`, which touches
65
+ nothing else.
66
+
67
+ That is bootstrap, not a loop authorizing itself, and the difference is
68
+ mechanical rather than a matter of intent: it only ever creates — an existing
69
+ policy is never read, merged or overwritten — and what it writes is the
70
+ shipped template byte for byte, the strictest default Tyran has. No input
71
+ makes it emit something weaker. Editing the file afterwards is human-only,
72
+ enforced exactly as before. Three tests pin the properties that make that
73
+ sentence true rather than aspirational: byte-identity with the template, an
74
+ untouched hand-written policy across setup and repair, and no `.tyran/` left
75
+ on disk when the install fails.
76
+
77
+ Two smaller things the same incident exposed. `doctor`'s `policy-missing`
78
+ finding was severity `info` — a repository where every tool call is denied,
79
+ reported as a note — and its suggested fix was a `cp` naming the policy path,
80
+ which the gate refuses when an agent runs it; it is now an `error` carrying a
81
+ command that works. And the documented `schema.mjs validate policy
82
+ .tyran/policies/…` line is one a **human** runs: inside a session it names a
83
+ path under `.tyran/policies/**` and is refused like any other. `doctor --state
84
+ --dir .tyran` validates the same file and names only the directory. The docs
85
+ say so now, and `/tyran:setup` runs the latter.
86
+
87
+ ## 0.1.0 — 2026-07-27
4
88
 
5
89
  ### Six protocol skills, and the budget raised once to pay for them
6
90
 
package/README.md CHANGED
@@ -21,11 +21,15 @@
21
21
  <h3 align="center">The more you use it, the better it gets.</h3>
22
22
 
23
23
  <p align="center">
24
- Tyran is a task conductor for Claude Code: it interviews you, plans, and drives a team of
25
- fresh-context agents through your work — <b>refusing to believe any agent that can't show
26
- raw command output as proof</b>, routing every subtask to the cheapest model that can do
27
- it, and keeping each agent in the context band where it still thinks clearly. When the
28
- work is done, it will not let the initiative end until it has learned something from it.
24
+ Never written a skill, spun up a subagent, or run an agent team yourself? Tyran does all
25
+ three automatically, on your behalf — and the retrospective it runs after every initiative
26
+ means it keeps learning your repo's way of working instead of repeating a generic playbook.
27
+ </p>
28
+
29
+ <p align="center">
30
+ Under the hood: it interviews you, plans, and drives a team of fresh-context agents through
31
+ your work, routing every subtask to the cheapest model that can actually do it — so a file
32
+ rename doesn't burn through your subscription at top-tier rates.
29
33
  </p>
30
34
 
31
35
  ---
@@ -142,7 +146,7 @@ Initiative 20 Has written repo-specific skills for your recurring work and
142
146
  ```text
143
147
  /plugin marketplace add jjanczur/tyran
144
148
  /plugin install tyran@tyran
145
- /tyran:setup # scans the repo, writes .tyran/config.yaml, installs /tyran
149
+ /tyran:setup # scans the repo, writes .tyran/, installs /tyran
146
150
  /tyran # then just describe what you want done
147
151
  ```
148
152
 
@@ -158,9 +162,11 @@ Install the Tyran plugin in this repository and set it up for me.
158
162
  1. Run: claude plugin marketplace add jjanczur/tyran
159
163
  2. Run: claude plugin install tyran@tyran
160
164
  3. Tell me to restart Claude Code, so the hooks and agents load.
161
- 4. After the restart, run /tyran:setup. It scans this repo and writes
162
- .tyran/config.yaml. Walk me through what it inferred - especially the
163
- validation commands and the deployment autonomy class - before we commit it.
165
+ 4. After the restart, run /tyran:setup, then /tyran:doctor. Setup writes the
166
+ two files under .tyran/ that Tyran needs - the config, and the autonomy
167
+ policy the write gate reads - and doctor proves the install actually
168
+ works. Walk me through what setup inferred - especially the validation
169
+ commands and the deployment autonomy class - before we commit it.
164
170
 
165
171
  Docs: https://jjanczur.github.io/tyran/getting-started/
166
172
  ```
@@ -278,10 +284,12 @@ echo "wrong branch — hold everything" > .tyran/STOP
278
284
  force-pushes are refused; a push to your production branch is refused at the
279
285
  strictest autonomy class, including through `HEAD`, `@`, a shell variable or
280
286
  a `git -c` alias. **What it does not do is stop an agent from raising the
281
- class itself:** the config file holding it is GATED, not KERNEL, so an agent
282
- with a broad allow-list can edit it in the main loop — measured, not
283
- supposed. Autonomy classes are a convention the gate enforces downward, not
284
- a lock. Not a firewall, and
287
+ class itself:** the config file holding it is `AUTO` in the shipped policy,
288
+ so an agent can edit it. That is deliberate — the same file holds your
289
+ validation commands, and an agent that cannot correct a wrong one is an
290
+ agent that runs your test suite wrong forever. Set the rule back to `GATED`
291
+ in one word if you want the other trade. Autonomy classes are a convention
292
+ the gate enforces downward, not a lock. Not a firewall, and
285
293
  [docs/hooks.md](docs/hooks.md) says exactly where it stops — including the
286
294
  scanner's own measured false-negative rate.
287
295
 
@@ -341,53 +349,48 @@ one directory each.</sub>
341
349
 
342
350
  ## Command-line use (outside Claude Code)
343
351
 
344
- A single `bin/tyran.mjs` entry point exposes the same scripts the plugin's
345
- hooks and skills already call — `doctor`, `scan-repo`, `tiers`, `journal`,
346
- `schema`, `stop-check`, `scan-control-chars`, `desc-budget` — for a shell or a
347
- CI job with no Claude Code session. Zero dependencies; `--help` lists them.
352
+ Published on npm as [`@jjanczur/tyran`](https://www.npmjs.com/package/@jjanczur/tyran)
353
+ — scoped, not the bare name `tyran`, which carries an unpublish tombstone from
354
+ 2021-03-30 that npm's abuse policy blocks anyone from reusing, permanently. The
355
+ command stays `tyran` either way; only the registry name is scoped, the same
356
+ pattern as `@angular/cli` giving you `ng`. `bin/tyran.mjs` exposes the same
357
+ scripts the plugin's hooks and skills already call — `doctor`, `scan-repo`,
358
+ `tiers`, `journal`, `schema`, `stop-check`, `scan-control-chars`,
359
+ `desc-budget` — for a shell or a CI job with no Claude Code session. Zero
360
+ dependencies; `--help` lists them.
348
361
 
349
362
  ```bash
350
- node bin/tyran.mjs doctor --hooks # is any gate installed but unable to fire?
351
- node bin/tyran.mjs scan-repo --dir . # what this repo looks like, with provenance
363
+ npx @jjanczur/tyran doctor --hooks # is any gate installed but unable to fire?
364
+ npx @jjanczur/tyran scan-repo --dir . # what this repo looks like, with provenance
352
365
  ```
353
366
 
354
367
  Exit codes propagate to the digit, so a CI step reddens exactly when the
355
368
  underlying script does.
356
369
 
357
- > **Not on npm yet — so `npx @jjanczur/tyran` does not work today.** The
358
- > package is built, versioned and tested; only the publish is outstanding.
359
- > Saying it works here before that is true would be exactly the kind of claim
360
- > this project refuses to accept from its own agents. It publishes under the
361
- > scope, not the bare name `tyran` — that name carries an npm unpublish
362
- > tombstone from 2021-03-30, and npm's policy against reusing an unpublished
363
- > name is permanent, for anyone, not a grace period this project could wait
364
- > out. The command stays `tyran` either way; only the registry name is scoped.
365
- >
366
- > **And it would not install the Claude Code plugin either.** For that, run
370
+ > **This does not install the Claude Code plugin.** For that, run
367
371
  > `/plugin marketplace add jjanczur/tyran` inside Claude Code — that name is
368
- > the Claude Code marketplace identity, a separate namespace from npm and
369
- > unaffected by any of the above. The npm package is the tooling; the plugin
370
- > is the conductor.
372
+ > the Claude Code marketplace identity, a separate namespace from npm. The npm
373
+ > package is the tooling; the plugin is the conductor.
371
374
 
372
375
  ## Documentation
373
376
 
374
377
  **Everything below also reads as a site: [jjanczur.github.io/tyran](https://jjanczur.github.io/tyran/)**
375
378
  — same text, with search, rendered diagrams and per-page status badges.
376
379
 
377
- - 📖 [Getting started](docs/getting-started.md)
378
- - 🧰 [Skills and agents](docs/skills.md) — all fourteen skills and four agents, what each assumes, and who invokes it
379
- - ⚙️ [Configuration](docs/configuration.md) — `.tyran/config.yaml`, cost profiles, autonomy classes
380
- - 🎭 [The roster and model routing](docs/agents.md) — the four agents, the tier and effort table, dynamic overrides, the `.tyran/STOP` brake (shipped)
381
- - 🏛️ [Architecture](docs/architecture.md) — the three layers, the journal, the hooks
382
- - 📜 [Journal reference](docs/journal.md) — the append-only event schema (shipped)
383
- - 🧾 [Projections](docs/projections.md) — generated `STATE.md` / `PROGRESS.md` and `--check` (shipped)
384
- - 🩺 [Doctor](docs/doctor.md) — `--state` consistency check: drift, orphan leases, dead policy rules (shipped)
385
- - 🪝 [Hook runtime](docs/hooks.md) — gates vs probes, why hooks fail open, and what the deadline really promises (shipped)
386
- - 🧾 [Evidence gate](docs/evidence-gate.md) — the criterion, who it binds, the recorded escape hatch, and the line between silence and forgery (shipped)
387
- - 🛡️ [Policy gate](docs/policy-gate.md) — path classes, the deployment class, the one rule on reads, and where each stops (shipped)
388
- - 🧠 [Self-improvement](docs/self-improvement.md) — how Tyran learns your repo, and its guardrails
389
- - ❓ [FAQ](docs/faq.md)
390
- - 🤝 [Contributing](CONTRIBUTING.md)
380
+ - 📖 [Getting started](https://jjanczur.github.io/tyran/getting-started/)
381
+ - 🧰 [Skills and agents](https://jjanczur.github.io/tyran/skills/) — all fourteen skills and four agents, what each assumes, and who invokes it
382
+ - ⚙️ [Configuration](https://jjanczur.github.io/tyran/configuration/) — `.tyran/config.yaml`, cost profiles, autonomy classes
383
+ - 🎭 [The roster and model routing](https://jjanczur.github.io/tyran/agents/) — the four agents, the tier and effort table, dynamic overrides, the `.tyran/STOP` brake (shipped)
384
+ - 🏛️ [Architecture](https://jjanczur.github.io/tyran/architecture/) — the three layers, the journal, the hooks
385
+ - 📜 [Journal reference](https://jjanczur.github.io/tyran/journal/) — the append-only event schema (shipped)
386
+ - 🧾 [Projections](https://jjanczur.github.io/tyran/projections/) — generated `STATE.md` / `PROGRESS.md` and `--check` (shipped)
387
+ - 🩺 [Doctor](https://jjanczur.github.io/tyran/doctor/) — `--state` consistency check: drift, orphan leases, dead policy rules (shipped)
388
+ - 🪝 [Hook runtime](https://jjanczur.github.io/tyran/hooks/) — gates vs probes, why hooks fail open, and what the deadline really promises (shipped)
389
+ - 🧾 [Evidence gate](https://jjanczur.github.io/tyran/evidence-gate/) — the criterion, who it binds, the recorded escape hatch, and the line between silence and forgery (shipped)
390
+ - 🛡️ [Policy gate](https://jjanczur.github.io/tyran/policy-gate/) — path classes, the deployment class, the one rule on reads, and where each stops (shipped)
391
+ - 🧠 [Self-improvement](https://jjanczur.github.io/tyran/self-improvement/) — how Tyran learns your repo, and its guardrails
392
+ - ❓ [FAQ](https://jjanczur.github.io/tyran/faq/)
393
+ - 🤝 [Contributing](CONTRIBUTING.md) — not a docs-site page, so this one stays a repo link
391
394
 
392
395
  ## Strategic principles
393
396
 
@@ -406,9 +409,9 @@ underlying script does.
406
409
  generalizable improvements travel to the core as pull requests.
407
410
  6. **Autonomy earns trust in layers.** Detected once, confirmed with you, and
408
411
  enforced downward by the policy gate. Not *"never self-escalated"* — the
409
- file holding the class is GATED rather than KERNEL, and an agent with a
410
- broad allow-list can edit it. Measured, not assumed; see
411
- [the policy gate](docs/policy-gate.md).
412
+ file holding the class is `AUTO`, so an agent can edit it, chosen so that
413
+ an agent can also repair the validation commands stored beside it.
414
+ Measured, not assumed; see [the policy gate](docs/policy-gate.md).
412
415
 
413
416
  ## Roadmap
414
417
 
@@ -1342,8 +1342,11 @@ const DEPLOY_REMEDY = Object.freeze(Object.assign(Object.create(null), {
1342
1342
  'recoverable from this session, which is the whole reason they are outside every autonomy class.',
1343
1343
  production:
1344
1344
  'What to do instead: push to your own branch and open a pull request. The class lives in ' +
1345
- `\`${CONFIG_PATH}\`, which ADR-06 classifies GATED rather than KERNEL, so raising it is an ` +
1346
- 'operator decision by CONVENTION, not by mechanism: measured in review, an agent in an ' +
1345
+ `\`${CONFIG_PATH}\`, and it is your own policy that decides whether an agent may edit that ` +
1346
+ 'file — the shipped template classifies it AUTO — so keeping the class where the operator put ' +
1347
+ 'it is by CONVENTION, not by mechanism. No class is named here on purpose: this text would ' +
1348
+ 'otherwise go stale the moment a repo reclassified the file, and a refusal that states the ' +
1349
+ 'wrong reason is worse than one that states none. Measured in review, an agent in an ' +
1347
1350
  'unattended main loop edited P1 to P3 with no refusal. Treat raising it yourself as the thing ' +
1348
1351
  'you were asked not to do, and say in your report that you wanted to.',
1349
1352
  shared:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -175,7 +175,10 @@ export const SEVERITY_BY_CODE = Object.freeze(
175
175
  'knowledge-invalid': 'error',
176
176
  'knowledge-unreadable': 'error',
177
177
  'knowledge-not-a-directory': 'warning',
178
- 'policy-missing': 'info',
178
+ // Not `info`, which is what it was: with `.tyran/` on disk and no policy
179
+ // under it the gate refuses every write in the repository. A severity that
180
+ // does not fail the check reports a locked-out repo as a note.
181
+ 'policy-missing': 'error',
179
182
  'policy-invalid': 'error',
180
183
  'policy-unreadable': 'error',
181
184
  'policies-unreadable': 'error',
@@ -1022,8 +1025,11 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1022
1025
  finding(
1023
1026
  'policy-missing',
1024
1027
  show(join(dir, 'policies')),
1025
- 'no autonomy policy — the self-improvement boundary (AUTO / GATED / KERNEL) is undefined for this repo',
1026
- `mkdir -p ${sq(join(dir, 'policies'))} && cp templates/policies/autonomy.yaml ${sq(join(dir, 'policies', 'autonomy.yaml'))}`,
1028
+ 'no autonomy policy, in a repo that HAS a .tyran/ directory — the policy gate fails closed on ' +
1029
+ 'exactly this state, so every write in every session is refused until the file exists. It is not ' +
1030
+ 'a missing nicety; the repository is unusable',
1031
+ `node scripts/scan-repo.mjs --dir ${sq(repoRoot)} --ensure-policy # installs the shipped template; ` +
1032
+ 'never overwrites a policy you wrote',
1027
1033
  ),
1028
1034
  );
1029
1035
  }
@@ -25,13 +25,15 @@
25
25
  *
26
26
  * CLI:
27
27
  * node scan-repo.mjs [--dir <repo>] [--write <path>] [--json]
28
+ * node scan-repo.mjs [--dir <repo>] --ensure-policy
28
29
  * Exit: 0 scanned · 2 usage/IO error
29
30
  */
30
- import { readFileSync, existsSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
31
+ import { readFileSync, existsSync, writeFileSync, mkdirSync, rmdirSync, realpathSync } from 'node:fs';
31
32
  import { execFileSync } from 'node:child_process';
32
- import { join, resolve, dirname, extname } from 'node:path';
33
+ import { join, resolve, dirname, extname, relative } from 'node:path';
33
34
  import { fileURLToPath } from 'node:url';
34
- import { stringify } from './yaml-lite.mjs';
35
+ import { parse, stringify } from './yaml-lite.mjs';
36
+ import { validatePolicy } from './schema.mjs';
35
37
  import { escapeInvisible } from './invisible.mjs';
36
38
 
37
39
  /** Lockfile -> package manager. Order matters only for reporting stability. */
@@ -242,6 +244,140 @@ export function renderConfig(config) {
242
244
  );
243
245
  }
244
246
 
247
+ // ------------------------------------------------------- bootstrapping the policy
248
+
249
+ /**
250
+ * The directory whose existence ARMS the policy gate, and the file that gate
251
+ * needs in order to answer anything.
252
+ */
253
+ export const TYRAN_DIR = '.tyran';
254
+ export const POLICY_PATH = '.tyran/policies/autonomy.yaml';
255
+
256
+ /**
257
+ * Seeding the policy is part of writing the config, and it is not optional.
258
+ *
259
+ * The policy gate is silent in a repository with no `.tyran/` directory — no
260
+ * adoption, nothing to say — and REFUSES every write in a repository that has
261
+ * one but no `.tyran/policies/autonomy.yaml`, because a boundary it cannot
262
+ * read must never read as an open one (ADR-22). Both halves are right. Their
263
+ * seam was not: `--write .tyran/config.yaml` created the directory and nothing
264
+ * created the policy, so setup's own first command moved the repo from
265
+ * "silent" to "refuses everything" — including the write that would have
266
+ * installed the missing file. Measured on a real install: the setup session
267
+ * ended with the operator being handed a `mkdir` and a `cp` to run by hand.
268
+ *
269
+ * Seeding it here is bootstrap, not self-authorization, and the difference is
270
+ * mechanical rather than a matter of intent:
271
+ *
272
+ * - it only ever CREATES. An existing policy is never read, never merged,
273
+ * never overwritten — `existsSync` returns first. So this cannot weaken a
274
+ * boundary that exists, which is the whole content of KERNEL;
275
+ * - what it writes is the shipped template byte for byte, which is the
276
+ * strictest default Tyran has (`default: GATED`, `hooks/**` and
277
+ * `.tyran/policies/**` KERNEL). There is no arrangement of inputs that
278
+ * makes it write something more permissive;
279
+ * - it is validated before it lands, so a damaged template becomes a loud
280
+ * exit 2 rather than a repository nobody can write to.
281
+ *
282
+ * Editing the policy afterwards is still human-only, by hand, and the gate
283
+ * still refuses `Write`, `Edit` and any shell command that names the path.
284
+ */
285
+ export class BootstrapError extends Error {
286
+ constructor(message, remedy) {
287
+ super(message);
288
+ this.name = 'BootstrapError';
289
+ this.remedy = remedy;
290
+ }
291
+ }
292
+
293
+ /** The shipped template, from this script's REAL location (see isMainModule). */
294
+ export function policyTemplatePath() {
295
+ const self = canonicalPath(fileURLToPath(import.meta.url));
296
+ return join(dirname(self), '..', 'templates', 'policies', 'autonomy.yaml');
297
+ }
298
+
299
+ /** True when writing `path` would create or populate the repo's `.tyran/`. */
300
+ export function underTyranDir(path, repoRoot) {
301
+ const rel = relative(resolve(repoRoot), resolve(path)).replace(/\\/g, '/');
302
+ return rel === TYRAN_DIR || rel.startsWith(`${TYRAN_DIR}/`);
303
+ }
304
+
305
+ /** The ancestors of `leaf` up to and including `stopAt` that do not exist yet. */
306
+ function absentAncestors(leaf, stopAt) {
307
+ const absent = [];
308
+ let cursor = resolve(leaf);
309
+ const root = resolve(stopAt);
310
+ while (cursor !== root && cursor !== dirname(cursor)) {
311
+ if (!existsSync(cursor)) absent.push(cursor);
312
+ cursor = dirname(cursor);
313
+ }
314
+ return absent;
315
+ }
316
+
317
+ /**
318
+ * Install `.tyran/policies/autonomy.yaml` from the shipped template if it is
319
+ * absent. Returns `{ path, status: 'created' | 'present' }`.
320
+ *
321
+ * On failure it removes the directories it created before throwing. That
322
+ * cleanup is the point rather than tidiness: a half-finished bootstrap leaves
323
+ * `.tyran/` on disk with no policy under it, which is exactly the state that
324
+ * refuses every subsequent write — the bug this function exists to prevent,
325
+ * reintroduced by its own error path.
326
+ */
327
+ export function ensureAutonomyPolicy(repoRoot, { templatePath = policyTemplatePath() } = {}) {
328
+ const root = resolve(repoRoot);
329
+ const path = join(root, ...POLICY_PATH.split('/'));
330
+ if (existsSync(path)) return { path, status: 'present' };
331
+
332
+ let text;
333
+ try {
334
+ text = readFileSync(templatePath, 'utf8');
335
+ } catch (error) {
336
+ throw new BootstrapError(
337
+ `the shipped policy template is unreadable at ${escapeInvisible(templatePath)}: ${error.message}`,
338
+ 'reinstall the plugin — this file ships with it, and without it a repository cannot be set up at all',
339
+ );
340
+ }
341
+
342
+ // Validated BEFORE it lands. A template that fails its own schema installs a
343
+ // repository the gate refuses on every write, and the operator then debugs a
344
+ // policy they never wrote.
345
+ let errors;
346
+ try {
347
+ errors = validatePolicy(parse(text));
348
+ } catch (error) {
349
+ errors = [`the template is not parseable YAML (${error.name})`];
350
+ }
351
+ if (errors.length > 0) {
352
+ throw new BootstrapError(
353
+ `the shipped policy template does not validate (${errors.length} finding(s); the first is ` +
354
+ `${escapeInvisible(String(errors[0]))})`,
355
+ 'this is a defect in the plugin, not in your repository. Report it rather than hand-editing the template.',
356
+ );
357
+ }
358
+
359
+ const created = absentAncestors(dirname(path), root);
360
+ try {
361
+ mkdirSync(dirname(path), { recursive: true });
362
+ writeFileSync(path, text);
363
+ } catch (error) {
364
+ for (const dir of created) {
365
+ // Deepest first, and only while empty — rmdirSync refuses a directory
366
+ // with anything in it, which is the behaviour to want here.
367
+ try {
368
+ rmdirSync(dir);
369
+ } catch {
370
+ break;
371
+ }
372
+ }
373
+ throw new BootstrapError(
374
+ `could not write ${escapeInvisible(path)}: ${error.message}`,
375
+ 'check the directory permissions; nothing was left behind, so re-running this command is safe',
376
+ );
377
+ }
378
+ return { path, status: 'created' };
379
+ }
380
+
245
381
  function main() {
246
382
  const args = process.argv.slice(2);
247
383
  const flag = (name, fallback) => {
@@ -254,10 +390,34 @@ function main() {
254
390
  process.exit(2);
255
391
  }
256
392
 
393
+ // Repair mode: seed the policy and do nothing else. This is what `doctor`
394
+ // hands an operator whose `.tyran/` predates this bootstrap, and it names no
395
+ // protected path on its command line, so it is a remedy an agent can run
396
+ // rather than a chore an agent has to delegate back to a human.
397
+ if (args.includes('--ensure-policy')) {
398
+ const seeded = seedPolicy(dir);
399
+ console.error(
400
+ seeded.status === 'created'
401
+ ? `scan-repo: created ${escapeInvisible(seeded.path)} from the shipped template`
402
+ : `scan-repo: ${escapeInvisible(seeded.path)} already exists — left untouched`,
403
+ );
404
+ return;
405
+ }
406
+
257
407
  const result = scanRepo(dir);
258
408
  const target = flag('write', null);
259
409
  if (target !== null) {
260
410
  const path = resolve(target);
411
+ // The boundary goes in FIRST. Between the mkdir that creates `.tyran/` and
412
+ // the write that puts a policy under it, every tool call in the session is
413
+ // refused; ordering it this way makes that window empty instead of
414
+ // permanent.
415
+ if (underTyranDir(path, dir)) {
416
+ const seeded = seedPolicy(dir);
417
+ if (seeded.status === 'created') {
418
+ console.error(`scan-repo: created ${escapeInvisible(seeded.path)} from the shipped template`);
419
+ }
420
+ }
261
421
  try {
262
422
  mkdirSync(dirname(path), { recursive: true });
263
423
  writeFileSync(path, renderConfig(result.config));
@@ -270,6 +430,18 @@ function main() {
270
430
  console.log(JSON.stringify(result, null, 2));
271
431
  }
272
432
 
433
+ /** `ensureAutonomyPolicy`, with a BootstrapError turned into exit 2. */
434
+ function seedPolicy(dir) {
435
+ try {
436
+ return ensureAutonomyPolicy(dir);
437
+ } catch (error) {
438
+ if (!(error instanceof BootstrapError)) throw error;
439
+ console.error(`scan-repo: ${error.message}`);
440
+ console.error(`scan-repo: ${error.remedy}`);
441
+ process.exit(2);
442
+ }
443
+ }
444
+
273
445
  function canonicalPath(path) {
274
446
  const abs = resolve(path);
275
447
  try {
@@ -20,6 +20,27 @@ an autonomy class inferred from how the repository is really worked. Every
20
20
  value carries the fact that produced it and a confidence, so months later
21
21
  "why does this repo think it is P2" has an answer in the file itself.
22
22
 
23
+ **It writes two files, and the second one is why this command is not
24
+ optional.** Before the config, it installs `.tyran/policies/autonomy.yaml`
25
+ from the shipped template. The policy gate is silent in a repository with no
26
+ `.tyran/` directory and refuses every write in a repository that has one
27
+ without a policy under it — so creating the config alone moves the repo from
28
+ "unmanaged" to "refuses everything", including the write that would have
29
+ fixed it. Setup did exactly that once, and the session ended with a `mkdir`
30
+ and a `cp` handed to the operator.
31
+
32
+ Installing it is bootstrap, not an agent granting itself permission: it only
33
+ ever creates, never overwrites, and what it writes is the strictest template
34
+ Tyran ships. Editing that file afterwards is human-only and stays so — the
35
+ gate refuses `Write`, `Edit`, and any shell command that names the path.
36
+
37
+ If you find a repository already in the broken state — `.tyran/` present, no
38
+ policy — this repairs it without touching anything else:
39
+
40
+ ```bash
41
+ node "${CLAUDE_PLUGIN_ROOT}/scripts/scan-repo.mjs" --dir . --ensure-policy
42
+ ```
43
+
23
44
  **It never infers `P3`.** No arrangement of files is evidence that a person
24
45
  meant to let an agent merge to main and deploy to production. That is a
25
46
  decision someone makes in words, and if the operator wants it they will say
@@ -71,9 +92,19 @@ someone's working tree unannounced is a bad way to meet a tool.
71
92
  node "${CLAUDE_PLUGIN_ROOT}/scripts/schema.mjs" validate config .tyran/config.yaml
72
93
  node "${CLAUDE_PLUGIN_ROOT}/scripts/tiers.mjs" --config .tyran/config.yaml
73
94
  node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs" --hooks
95
+ node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs" --state --dir .tyran
74
96
  ```
75
97
 
76
- Report in five lines: what was detected, what was inferred and from what,
77
- what you asked about, whether the shortcut was installed, and what to run
78
- next. Paste the raw output of the three commands above — the evidence
79
- contract binds you exactly as it binds every agent you will spawn.
98
+ The `--state` run is the one that answers "is this repo actually usable now",
99
+ and it is also how you validate the policy. Do **not** reach for
100
+ `schema.mjs validate policy .tyran/policies/autonomy.yaml`: the gate refuses
101
+ any shell command that names a path under `.tyran/policies/**`, including
102
+ that one. `doctor --state` validates the same file and names only `.tyran`.
103
+ A `policy-missing` finding there is an **error**, not a note — it means every
104
+ write in the repo is being refused.
105
+
106
+ Report in six lines: what was detected, what was inferred and from what, what
107
+ you asked about, that both `.tyran/` files are in place and validate, whether
108
+ the shortcut was installed, and what to run next. Paste the raw output of the
109
+ commands above — the evidence contract binds you exactly as it binds every
110
+ agent you will spawn.
@@ -32,9 +32,21 @@ rules:
32
32
  class: AUTO
33
33
  reason: the execution journal is append-only and written by the conductor itself
34
34
 
35
+ # Was GATED. The cost was measured on a real install: setup had inferred
36
+ # `pnpm test`, which in that repo is bare `vitest` — it never exits, so every
37
+ # agent would have hung forever. The session that FOUND that could not fix it,
38
+ # and handed the operator a heredoc to paste. A boundary that blocks the repair
39
+ # of a footgun it created is one the user edits away, and then it protects
40
+ # nothing at all.
41
+ #
42
+ # What this gives up, in one sentence, because an unstated cost is a false
43
+ # guarantee: `autonomy:` lives in this file too, so an agent can now raise its
44
+ # own deployment class. Set this rule back to GATED if that trade is wrong for
45
+ # your repo — and read `docs/policy-gate.md`, which measured the same
46
+ # escalation happening under GATED anyway wherever `Write` is allow-listed.
35
47
  - path: .tyran/config.yaml
36
- class: GATED
37
- reason: autonomy class and model routing live here, so this file sets both what Tyran may do and what it may spend
48
+ class: AUTO
49
+ 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
38
50
 
39
51
  - path: .claude/agents/**
40
52
  class: GATED