@jjanczur/tyran 0.1.0 → 0.1.4

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.
@@ -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. */
@@ -90,9 +92,57 @@ export function gitRunner(dir) {
90
92
  };
91
93
  }
92
94
 
93
- export function detectPackageManager(dir) {
94
- for (const [file, manager] of Object.entries(LOCKFILES)) {
95
- if (existsSync(join(dir, file))) return provenance(manager, `lockfile: ${file}`, 0.95);
95
+ /** The repo's tracked files as a Set, or null when git could not answer. */
96
+ export function trackedFiles(run) {
97
+ const listing = run(['ls-files']);
98
+ if (listing === '') return null;
99
+ return new Set(listing.split('\n').filter((line) => line !== ''));
100
+ }
101
+
102
+ /**
103
+ * Which package manager this repo actually uses.
104
+ *
105
+ * A lockfile being ON DISK is not evidence that it is the repo's lockfile.
106
+ * Measured on a real install: the repo had both `pnpm-lock.yaml` and
107
+ * `package-lock.json`, `pnpm-lock.yaml` was gitignored and untracked, and
108
+ * `.gitignore` said in words that the npm lockfile was authoritative. Picking
109
+ * by disk order chose pnpm, and then EVERY validation command was wrong —
110
+ * `pnpm lint`, `pnpm typecheck`, `pnpm test` in a repo with no pnpm.
111
+ *
112
+ * So git is asked which lockfiles it tracks, and a tracked one wins. The
113
+ * distinction that keeps this honest: `git ls-files` returning NOTHING means
114
+ * git could not answer (no repository, nothing committed yet), and no
115
+ * conclusion is drawn from it. A non-empty listing that omits a lockfile is
116
+ * positive evidence that the file is ignored or untracked, and that is the
117
+ * only case that changes the answer.
118
+ */
119
+ export function detectPackageManager(dir, run = gitRunner(dir)) {
120
+ const present = Object.entries(LOCKFILES).filter(([file]) => existsSync(join(dir, file)));
121
+ if (present.length > 0) {
122
+ const tracked = trackedFiles(run);
123
+ if (tracked === null) {
124
+ const [file, manager] = present[0];
125
+ return provenance(manager, `lockfile: ${file}`, 0.95);
126
+ }
127
+ const inGit = present.filter(([file]) => tracked.has(file));
128
+ if (inGit.length > 0) {
129
+ const [file, manager] = inGit[0];
130
+ const ignored = present.filter(([f]) => !tracked.has(f)).map(([f]) => f);
131
+ const source =
132
+ ignored.length === 0
133
+ ? `lockfile: ${file}`
134
+ : `lockfile: ${file} — tracked by git, unlike ${ignored.join(', ')}, which git does not track`;
135
+ return provenance(manager, source, 0.95);
136
+ }
137
+ // On disk, none of them committed. Something is the answer here, but the
138
+ // repository is not saying which — so it is a flagged guess, not a fact.
139
+ const [file, manager] = present[0];
140
+ return provenance(
141
+ manager,
142
+ `lockfile: ${file}, but git tracks no lockfile at all — this one may be ignored`,
143
+ 0.4,
144
+ true,
145
+ );
96
146
  }
97
147
  if (existsSync(join(dir, 'package.json'))) {
98
148
  return provenance('npm', 'package.json with no lockfile — npm assumed', 0.5, true);
@@ -117,12 +167,77 @@ export function readPackageJson(dir) {
117
167
  * gate is noise. When nothing can be read, the list comes back empty and
118
168
  * flagged rather than filled in with `npm test`.
119
169
  */
170
+ /**
171
+ * Suffixes a repo uses for "the same thing, but it exits". Tried in order.
172
+ */
173
+ export const RUN_ONCE_SUFFIXES = Object.freeze([':run', ':ci', ':once']);
174
+
175
+ /**
176
+ * Why this script would never return, or null.
177
+ *
178
+ * This is the single most dangerous inference the scanner can make. A
179
+ * validation command that watches instead of exiting does not fail the agent
180
+ * that runs it — it HANGS it, with no output and no timeout, and the operator
181
+ * sees a session that has simply stopped. Measured on a real install: setup
182
+ * wrote `pnpm test`, whose script was bare `vitest`, and every agent handed
183
+ * that gate would have waited forever.
184
+ *
185
+ * Deliberately narrow, because a false positive here drops a real test command
186
+ * out of the config. `jest` is NOT listed: it runs once by default and only
187
+ * watches when told to, so the explicit-flag rule below already covers it.
188
+ */
189
+ export function watchModeProblem(script) {
190
+ const text = String(script);
191
+ if (/(^|[\s;&|])nodemon(\s|$)/.test(text)) return 'runs `nodemon`, which watches and never exits';
192
+ if (/--watch(All|-all)?\b(?!=false)/.test(text)) return 'passes --watch, so it never exits';
193
+ // `vitest` with no subcommand is watch mode outside CI. `vitest run`,
194
+ // `vitest bench` and an explicit `--run` all terminate.
195
+ if (/(^|[\s;&|])vitest(\s|$)/.test(text) && !/(^|\s)vitest\s+(run|bench|related)\b/.test(text) && !/--run\b/.test(text)) {
196
+ return 'is bare `vitest`, which defaults to watch mode and never exits';
197
+ }
198
+ return null;
199
+ }
200
+
201
+ /**
202
+ * The script to actually run for `name`, avoiding a watcher.
203
+ *
204
+ * Returns `{ script, note }` — `script` null when every candidate watches,
205
+ * which is a command deliberately LEFT OUT rather than written into a config
206
+ * where it would hang the first agent that trusted it.
207
+ */
208
+ export function resolveValidationScript(scripts, name) {
209
+ const problem = watchModeProblem(scripts[name]);
210
+ if (problem === null) return { script: name, note: null };
211
+ for (const suffix of RUN_ONCE_SUFFIXES) {
212
+ const alternate = `${name}${suffix}`;
213
+ if (typeof scripts[alternate] === 'string' && watchModeProblem(scripts[alternate]) === null) {
214
+ return { script: alternate, note: `\`${name}\` ${problem}, so \`${alternate}\` is used instead` };
215
+ }
216
+ }
217
+ return { script: null, note: `\`${name}\` ${problem}, and no run-once variant exists — left out` };
218
+ }
219
+
120
220
  export function detectValidation(dir, pkg, manager) {
121
221
  const scripts = pkg?.scripts;
122
222
  if (scripts && typeof scripts === 'object') {
123
223
  const prefix = RUN_PREFIX[manager] ?? 'npm run';
124
- const found = VALIDATION_SCRIPTS.filter((name) => typeof scripts[name] === 'string').map((n) => `${prefix} ${n}`);
125
- if (found.length > 0) return provenance(found, `package.json scripts: ${found.length} of the usual names`, 0.9);
224
+ const found = [];
225
+ const notes = [];
226
+ let dropped = false;
227
+ for (const name of VALIDATION_SCRIPTS) {
228
+ if (typeof scripts[name] !== 'string') continue;
229
+ const { script, note } = resolveValidationScript(scripts, name);
230
+ if (note !== null) notes.push(note);
231
+ if (script === null) dropped = true;
232
+ else found.push(`${prefix} ${script}`);
233
+ }
234
+ if (found.length > 0 || notes.length > 0) {
235
+ const base = `package.json scripts: ${found.length} of the usual names`;
236
+ const source = notes.length === 0 ? base : `${base}. ${notes.join('; ')}`;
237
+ // A dropped command means this repo's validation is INCOMPLETE, and the
238
+ // operator is the only one who can say what to run instead.
239
+ return provenance(found, source, dropped ? 0.6 : 0.9, dropped);
240
+ }
126
241
  }
127
242
  if (existsSync(join(dir, 'Makefile'))) {
128
243
  try {
@@ -200,7 +315,7 @@ export function detectAutonomy(dir, run = gitRunner(dir)) {
200
315
  /** The whole scan. Returns `{config, languages, questions}`. */
201
316
  export function scanRepo(dir, { run = gitRunner(dir) } = {}) {
202
317
  const pkg = readPackageJson(dir);
203
- const manager = detectPackageManager(dir);
318
+ const manager = detectPackageManager(dir, run);
204
319
  const validation = detectValidation(dir, pkg, manager?.value);
205
320
  const autonomy = detectAutonomy(dir, run);
206
321
  const languages = detectLanguages(dir, run);
@@ -235,6 +350,16 @@ export function renderConfig(config) {
235
350
  '# Written by /tyran:setup. Inferred values carry provenance so you can\n' +
236
351
  '# audit where each one came from. Edit freely — your edits win.\n' +
237
352
  '#\n' +
353
+ '# EDITING BY HAND: Tyran parses a small YAML subset. Block scalars (>- and\n' +
354
+ '# |-) are REJECTED, and a file this parser cannot read makes the policy\n' +
355
+ '# gate refuse every write in this repository. Keep each `source:` on ONE\n' +
356
+ '# line, single-quoted, however long it gets.\n' +
357
+ '#\n' +
358
+ '# COMMIT THIS DIRECTORY. `.tyran/` is your repo\'s data, and an untracked\n' +
359
+ '# one does not reach `git worktree add` — agents then run there with no\n' +
360
+ '# autonomy class at all, which is the boundary silently missing exactly\n' +
361
+ '# where the most agents run.\n' +
362
+ '#\n' +
238
363
  '# Validate: node scripts/schema.mjs validate config .tyran/config.yaml\n' +
239
364
  '# Resolve a role to a model: node scripts/tiers.mjs --role reviewer\n' +
240
365
  '\n' +
@@ -242,6 +367,140 @@ export function renderConfig(config) {
242
367
  );
243
368
  }
244
369
 
370
+ // ------------------------------------------------------- bootstrapping the policy
371
+
372
+ /**
373
+ * The directory whose existence ARMS the policy gate, and the file that gate
374
+ * needs in order to answer anything.
375
+ */
376
+ export const TYRAN_DIR = '.tyran';
377
+ export const POLICY_PATH = '.tyran/policies/autonomy.yaml';
378
+
379
+ /**
380
+ * Seeding the policy is part of writing the config, and it is not optional.
381
+ *
382
+ * The policy gate is silent in a repository with no `.tyran/` directory — no
383
+ * adoption, nothing to say — and REFUSES every write in a repository that has
384
+ * one but no `.tyran/policies/autonomy.yaml`, because a boundary it cannot
385
+ * read must never read as an open one (ADR-22). Both halves are right. Their
386
+ * seam was not: `--write .tyran/config.yaml` created the directory and nothing
387
+ * created the policy, so setup's own first command moved the repo from
388
+ * "silent" to "refuses everything" — including the write that would have
389
+ * installed the missing file. Measured on a real install: the setup session
390
+ * ended with the operator being handed a `mkdir` and a `cp` to run by hand.
391
+ *
392
+ * Seeding it here is bootstrap, not self-authorization, and the difference is
393
+ * mechanical rather than a matter of intent:
394
+ *
395
+ * - it only ever CREATES. An existing policy is never read, never merged,
396
+ * never overwritten — `existsSync` returns first. So this cannot weaken a
397
+ * boundary that exists, which is the whole content of KERNEL;
398
+ * - what it writes is the shipped template byte for byte, which is the
399
+ * strictest default Tyran has (`default: GATED`, `hooks/**` and
400
+ * `.tyran/policies/**` KERNEL). There is no arrangement of inputs that
401
+ * makes it write something more permissive;
402
+ * - it is validated before it lands, so a damaged template becomes a loud
403
+ * exit 2 rather than a repository nobody can write to.
404
+ *
405
+ * Editing the policy afterwards is still human-only, by hand, and the gate
406
+ * still refuses `Write`, `Edit` and any shell command that names the path.
407
+ */
408
+ export class BootstrapError extends Error {
409
+ constructor(message, remedy) {
410
+ super(message);
411
+ this.name = 'BootstrapError';
412
+ this.remedy = remedy;
413
+ }
414
+ }
415
+
416
+ /** The shipped template, from this script's REAL location (see isMainModule). */
417
+ export function policyTemplatePath() {
418
+ const self = canonicalPath(fileURLToPath(import.meta.url));
419
+ return join(dirname(self), '..', 'templates', 'policies', 'autonomy.yaml');
420
+ }
421
+
422
+ /** True when writing `path` would create or populate the repo's `.tyran/`. */
423
+ export function underTyranDir(path, repoRoot) {
424
+ const rel = relative(resolve(repoRoot), resolve(path)).replace(/\\/g, '/');
425
+ return rel === TYRAN_DIR || rel.startsWith(`${TYRAN_DIR}/`);
426
+ }
427
+
428
+ /** The ancestors of `leaf` up to and including `stopAt` that do not exist yet. */
429
+ function absentAncestors(leaf, stopAt) {
430
+ const absent = [];
431
+ let cursor = resolve(leaf);
432
+ const root = resolve(stopAt);
433
+ while (cursor !== root && cursor !== dirname(cursor)) {
434
+ if (!existsSync(cursor)) absent.push(cursor);
435
+ cursor = dirname(cursor);
436
+ }
437
+ return absent;
438
+ }
439
+
440
+ /**
441
+ * Install `.tyran/policies/autonomy.yaml` from the shipped template if it is
442
+ * absent. Returns `{ path, status: 'created' | 'present' }`.
443
+ *
444
+ * On failure it removes the directories it created before throwing. That
445
+ * cleanup is the point rather than tidiness: a half-finished bootstrap leaves
446
+ * `.tyran/` on disk with no policy under it, which is exactly the state that
447
+ * refuses every subsequent write — the bug this function exists to prevent,
448
+ * reintroduced by its own error path.
449
+ */
450
+ export function ensureAutonomyPolicy(repoRoot, { templatePath = policyTemplatePath() } = {}) {
451
+ const root = resolve(repoRoot);
452
+ const path = join(root, ...POLICY_PATH.split('/'));
453
+ if (existsSync(path)) return { path, status: 'present' };
454
+
455
+ let text;
456
+ try {
457
+ text = readFileSync(templatePath, 'utf8');
458
+ } catch (error) {
459
+ throw new BootstrapError(
460
+ `the shipped policy template is unreadable at ${escapeInvisible(templatePath)}: ${error.message}`,
461
+ 'reinstall the plugin — this file ships with it, and without it a repository cannot be set up at all',
462
+ );
463
+ }
464
+
465
+ // Validated BEFORE it lands. A template that fails its own schema installs a
466
+ // repository the gate refuses on every write, and the operator then debugs a
467
+ // policy they never wrote.
468
+ let errors;
469
+ try {
470
+ errors = validatePolicy(parse(text));
471
+ } catch (error) {
472
+ errors = [`the template is not parseable YAML (${error.name})`];
473
+ }
474
+ if (errors.length > 0) {
475
+ throw new BootstrapError(
476
+ `the shipped policy template does not validate (${errors.length} finding(s); the first is ` +
477
+ `${escapeInvisible(String(errors[0]))})`,
478
+ 'this is a defect in the plugin, not in your repository. Report it rather than hand-editing the template.',
479
+ );
480
+ }
481
+
482
+ const created = absentAncestors(dirname(path), root);
483
+ try {
484
+ mkdirSync(dirname(path), { recursive: true });
485
+ writeFileSync(path, text);
486
+ } catch (error) {
487
+ for (const dir of created) {
488
+ // Deepest first, and only while empty — rmdirSync refuses a directory
489
+ // with anything in it, which is the behaviour to want here.
490
+ try {
491
+ rmdirSync(dir);
492
+ } catch {
493
+ break;
494
+ }
495
+ }
496
+ throw new BootstrapError(
497
+ `could not write ${escapeInvisible(path)}: ${error.message}`,
498
+ 'check the directory permissions; nothing was left behind, so re-running this command is safe',
499
+ );
500
+ }
501
+ return { path, status: 'created' };
502
+ }
503
+
245
504
  function main() {
246
505
  const args = process.argv.slice(2);
247
506
  const flag = (name, fallback) => {
@@ -254,10 +513,34 @@ function main() {
254
513
  process.exit(2);
255
514
  }
256
515
 
516
+ // Repair mode: seed the policy and do nothing else. This is what `doctor`
517
+ // hands an operator whose `.tyran/` predates this bootstrap, and it names no
518
+ // protected path on its command line, so it is a remedy an agent can run
519
+ // rather than a chore an agent has to delegate back to a human.
520
+ if (args.includes('--ensure-policy')) {
521
+ const seeded = seedPolicy(dir);
522
+ console.error(
523
+ seeded.status === 'created'
524
+ ? `scan-repo: created ${escapeInvisible(seeded.path)} from the shipped template`
525
+ : `scan-repo: ${escapeInvisible(seeded.path)} already exists — left untouched`,
526
+ );
527
+ return;
528
+ }
529
+
257
530
  const result = scanRepo(dir);
258
531
  const target = flag('write', null);
259
532
  if (target !== null) {
260
533
  const path = resolve(target);
534
+ // The boundary goes in FIRST. Between the mkdir that creates `.tyran/` and
535
+ // the write that puts a policy under it, every tool call in the session is
536
+ // refused; ordering it this way makes that window empty instead of
537
+ // permanent.
538
+ if (underTyranDir(path, dir)) {
539
+ const seeded = seedPolicy(dir);
540
+ if (seeded.status === 'created') {
541
+ console.error(`scan-repo: created ${escapeInvisible(seeded.path)} from the shipped template`);
542
+ }
543
+ }
261
544
  try {
262
545
  mkdirSync(dirname(path), { recursive: true });
263
546
  writeFileSync(path, renderConfig(result.config));
@@ -270,6 +553,18 @@ function main() {
270
553
  console.log(JSON.stringify(result, null, 2));
271
554
  }
272
555
 
556
+ /** `ensureAutonomyPolicy`, with a BootstrapError turned into exit 2. */
557
+ function seedPolicy(dir) {
558
+ try {
559
+ return ensureAutonomyPolicy(dir);
560
+ } catch (error) {
561
+ if (!(error instanceof BootstrapError)) throw error;
562
+ console.error(`scan-repo: ${error.message}`);
563
+ console.error(`scan-repo: ${error.remedy}`);
564
+ process.exit(2);
565
+ }
566
+ }
567
+
273
568
  function canonicalPath(path) {
274
569
  const abs = resolve(path);
275
570
  try {
@@ -133,7 +133,28 @@ function stripComment(line, lineNo) {
133
133
  // YAML loader (`a: don't ask # why`) — refuse rather than guess
134
134
  // (review E2S2 note 1).
135
135
  if (inSingle || inDouble) {
136
- throw new YamlLiteError('unbalanced quote — quote the whole value if it contains an apostrophe', lineNo);
136
+ // Name the construct, not one guess at its cause.
137
+ //
138
+ // This said "quote the whole value if it contains an apostrophe" for every
139
+ // unbalanced quote there is. Measured on a real install: an operator wrote
140
+ // a long `source:` as a multi-line double-quoted string, got told to worry
141
+ // about an apostrophe that was not there, and burned three round-trips
142
+ // looking for one. A diagnosis that confidently names the wrong cause is
143
+ // worse than one that names none — it sends the reader somewhere else.
144
+ //
145
+ // The two cases are distinguishable from what is already known here: a
146
+ // value that OPENS with the quote still in flight was never closed on this
147
+ // line, which in a subset with no multi-line scalars is the whole answer.
148
+ const opener = inSingle ? "'" : '"';
149
+ const body = line.slice(line.indexOf(':') + 1).trim();
150
+ const opensWithQuote = body.startsWith(opener);
151
+ throw new YamlLiteError(
152
+ opensWithQuote
153
+ ? `a ${opener}-quoted value that never closes on this line. This subset has no multi-line ` +
154
+ 'scalars (no >-, no |), so put the whole value on one line however long it gets'
155
+ : `unbalanced ${opener} — if the value contains an apostrophe, quote the whole value`,
156
+ lineNo,
157
+ );
137
158
  }
138
159
  return cut === -1 ? line : line.slice(0, cut);
139
160
  }
@@ -236,6 +236,28 @@ open one.
236
236
  sets only; a git worktree per agent; shared zones (per the manifest in
237
237
  `PLAN.md`) are APPEND-ONLY and serialized; a branch per story; rebase
238
238
  before merge.
239
+ - **A fresh worktree has no dependencies, so every validation command in
240
+ the config fails at once.** `npm run lint`, the type check and the test
241
+ suite all exit 127 in a new worktree, and the evidence contract then
242
+ cannot be satisfied by construction — measured on a Node repo, and the
243
+ same holds for `.venv`, `vendor/` and `target/`. Link the main checkout's
244
+ dependency directory into the worktree rather than installing: the
245
+ manifest and lockfile are already a SHARED ZONE nobody may edit, so the
246
+ dependencies are guaranteed identical, and a per-worktree install is how
247
+ a lockfile drifts. Say in the handoff which directory you linked.
248
+ - **`.tyran/state/**` lives in the main checkout only.** An agent told to
249
+ append to `NOTES.md` from inside a worktree must use the absolute
250
+ main-repo path, or it writes into a copy nobody reads.
251
+ - **A worktree without `.tyran/` is an UNGATED worktree.** `git worktree
252
+ add` carries tracked files only, so an uncommitted `.tyran/` does not
253
+ reach one — and the policy gate is deliberately silent in a repo that has
254
+ no `.tyran/` at all. The agents there then run with no autonomy class and
255
+ no path classes: nothing fails, the boundary is simply absent, in the one
256
+ place you are running the most agents. Measured on a real install: four
257
+ worktrees, four ungated implementers. So **check every worktree you
258
+ create** and, if `.tyran/` is missing, get it committed on the main
259
+ checkout first rather than copying it in — a copy makes four divergent
260
+ configs, which is the same defect one layer down.
239
261
  - **Leases are files.** Every worktree and every heavy slot has
240
262
  `.tyran/initiatives/<slug>/locks/<resource>.lease` holding holder,
241
263
  purpose, story and expiry. A handoff BEGINS by taking the lease — an
@@ -270,6 +292,12 @@ open one.
270
292
  a reply unless it is a gate.
271
293
  - Final report: what was built · how it was verified · everything in
272
294
  `NOTES.md` · the list of things the operator should check by hand.
295
+ - **You are notified when a subagent finishes — do not poll for it.** The
296
+ reflex is to set a repeating check; measured on a real run, most of those
297
+ fired after the agent had already reported, producing dozens of stale
298
+ notifications the conductor then had to disown in front of the operator.
299
+ Reserve a long fallback interval for work the harness cannot track, such as
300
+ a remote CI run.
273
301
  - **The retrospective is not optional and not on your memory.** When every
274
302
  ticket in an initiative is merged and no retrospective has been recorded
275
303
  since the last merge, the `Stop` gate refuses one turn and says so. Run
@@ -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,41 @@ 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
96
+ ```
97
+
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.
111
+
112
+ ## 6. Tell the operator to commit `.tyran/`, and say why
113
+
114
+ End by asking for one commit of `.tyran/`. This is not tidiness, and the
115
+ reason is the one failure mode of this whole setup that is **silent**:
116
+
117
+ ```bash
118
+ git add .tyran && git commit -m "chore: adopt Tyran"
74
119
  ```
75
120
 
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.
121
+ `git worktree add` does not carry untracked files. Tyran's parallel model is
122
+ worktrees, so an uncommitted `.tyran/` means every worktree the conductor
123
+ creates has no config and no policy — and a repo with no `.tyran/` is a repo
124
+ the policy gate deliberately says nothing about. The agents running in those
125
+ worktrees then have no autonomy class and no path classes at all. Nothing
126
+ fails; the boundary is simply not there, in exactly the place the most agents
127
+ run. Measured on a real install: four worktrees, four ungated implementers.
128
+
129
+ Until it is committed there is a second hazard worth naming in your report: an
130
+ agent that runs `git add -A` on a story branch sweeps the untracked `.tyran/`
131
+ into that branch, and a four-way parallel run ends with four conflicting
132
+ copies of the config. Stage explicit paths until this commit exists.
@@ -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