@jjanczur/tyran 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +164 -1
- package/README.md +52 -49
- package/hooks/scripts/policy-gate.mjs +5 -2
- package/package.json +1 -1
- package/scripts/doctor.mjs +58 -6
- package/scripts/scan-repo.mjs +304 -9
- package/scripts/yaml-lite.mjs +22 -1
- package/skills/run/SKILL.md +10 -0
- package/skills/setup/SKILL.md +57 -4
- package/templates/policies/autonomy.yaml +14 -2
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
{
|
|
12
12
|
"name": "tyran",
|
|
13
13
|
"description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
|
|
14
|
-
"version": "0.1.
|
|
14
|
+
"version": "0.1.2",
|
|
15
15
|
"source": "./",
|
|
16
16
|
"author": {
|
|
17
17
|
"name": "Jacek Janczura",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
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,169 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## 0.1.
|
|
3
|
+
## 0.1.2 — 2026-07-29
|
|
4
|
+
|
|
5
|
+
From a field report on a real 0.1.1 install. Every item below is a failure
|
|
6
|
+
somebody hit, not one anybody predicted.
|
|
7
|
+
|
|
8
|
+
### The worktree with no boundary
|
|
9
|
+
|
|
10
|
+
**`git worktree add` carries tracked files only, and the policy gate is
|
|
11
|
+
deliberately silent in a repo with no `.tyran/`.** Put those together and an
|
|
12
|
+
uncommitted `.tyran/` means every worktree the conductor creates has no config
|
|
13
|
+
and no policy — so the agents there run with **no autonomy class and no path
|
|
14
|
+
classes at all**. Nothing is refused, nothing fails, and `git push origin main`
|
|
15
|
+
returns `PASS` on line 1213 of the gate. Measured: four worktrees, four ungated
|
|
16
|
+
implementers, and no way for the operator to see it.
|
|
17
|
+
|
|
18
|
+
This is the worst kind of defect this project can have, because Tyran's whole
|
|
19
|
+
argument is that the boundary is a mechanism rather than a promise — and here
|
|
20
|
+
it was absent precisely where the most agents run.
|
|
21
|
+
|
|
22
|
+
Three changes, none of which touch the gate:
|
|
23
|
+
|
|
24
|
+
- `doctor --state` gains **`tyran-dir-untracked`** (warning): git is asked
|
|
25
|
+
whether anything under `.tyran/` is tracked. It returns *no answer* outside a
|
|
26
|
+
work tree rather than inventing one, the same discipline the lockfile rule
|
|
27
|
+
below uses;
|
|
28
|
+
- `/tyran:setup` now ends by asking for the commit, **with the reason**, rather
|
|
29
|
+
than leaving `.tyran/` sitting untracked;
|
|
30
|
+
- the conductor treats a worktree without `.tyran/` as a precondition failure,
|
|
31
|
+
and is told to fix it by committing on the main checkout — not by copying the
|
|
32
|
+
file in, which just makes four divergent configs one layer down.
|
|
33
|
+
|
|
34
|
+
### Two inferences that produced a broken gate
|
|
35
|
+
|
|
36
|
+
**A validation command that watches does not fail an agent, it hangs it.**
|
|
37
|
+
Setup wrote `pnpm test` into a repo whose `test` script is bare `vitest` —
|
|
38
|
+
watch mode, no output, no timeout, a session that simply stops. `detectValidation`
|
|
39
|
+
now reroutes to a run-once variant (`test:run`, `test:ci`, `test:once`) and, if
|
|
40
|
+
there is none, **leaves the command out** and flags the config rather than
|
|
41
|
+
writing a booby trap. The rule is deliberately narrow — `jest` runs once by
|
|
42
|
+
default and is not treated as a watcher — because a false positive here silently
|
|
43
|
+
drops a real test command.
|
|
44
|
+
|
|
45
|
+
**A lockfile on disk is not evidence that it is the repo's lockfile.** The same
|
|
46
|
+
install had `pnpm-lock.yaml` gitignored and untracked alongside the tracked
|
|
47
|
+
`package-lock.json` that its deploy actually builds from, and `.gitignore` said
|
|
48
|
+
so in words. Picking by disk order chose pnpm, and then every single validation
|
|
49
|
+
command was wrong. `detectPackageManager` now asks git which lockfiles are
|
|
50
|
+
tracked and says which one it rejected. An empty `git ls-files` means git could
|
|
51
|
+
not answer and changes nothing — "not a git repo" is not evidence that a file is
|
|
52
|
+
ignored.
|
|
53
|
+
|
|
54
|
+
Both replay clean against the repository that produced them.
|
|
55
|
+
|
|
56
|
+
### Errors that named the wrong cause
|
|
57
|
+
|
|
58
|
+
`yaml-lite` answered every unbalanced quote with *"quote the whole value if it
|
|
59
|
+
contains an apostrophe"*. An operator writing a long `source:` as a multi-line
|
|
60
|
+
double-quoted string was sent hunting an apostrophe that did not exist, three
|
|
61
|
+
times. A value that opens a quote and never closes it now says exactly that,
|
|
62
|
+
and says the subset has no multi-line scalars. The apostrophe advice survives
|
|
63
|
+
only on the case it is actually about.
|
|
64
|
+
|
|
65
|
+
`doctor.mjs` with no flag printed *"--state is the only mode today"* long after
|
|
66
|
+
`--hooks` shipped, sending readers to look for a flag they already had.
|
|
67
|
+
|
|
68
|
+
The generated `config.yaml` header now states the YAML subset and asks for the
|
|
69
|
+
commit, since both traps are sprung by hand-editing a file whose constraints
|
|
70
|
+
were documented somewhere else.
|
|
71
|
+
|
|
72
|
+
### Still open, deliberately
|
|
73
|
+
|
|
74
|
+
The report also found that the gate matches on command TEXT, so `ls -1 .npmrc`
|
|
75
|
+
is refused as a credential read though it reads nothing, and that a `GATED`
|
|
76
|
+
refusal tells an agent to write a diff for the operator while `outside this
|
|
77
|
+
repository is never autonomous` refuses the scratch directory that is the
|
|
78
|
+
obvious place to put it. That second one is self-defeating and worth fixing.
|
|
79
|
+
Both are changes to refusal semantics in a KERNEL file and are not being made
|
|
80
|
+
in the same pass as everything above.
|
|
81
|
+
|
|
82
|
+
## 0.1.1 — 2026-07-29
|
|
83
|
+
|
|
84
|
+
Both entries below come from one install of 0.1.0 on a real repository. The
|
|
85
|
+
version is bumped rather than folded into 0.1.0 because `claude plugin update`
|
|
86
|
+
compares **versions**, not commits: with the manifest left at 0.1.0 it reports
|
|
87
|
+
"already at the latest version" and users never receive the fix.
|
|
88
|
+
|
|
89
|
+
### `.tyran/config.yaml` is AUTO, and what that costs is written down
|
|
90
|
+
|
|
91
|
+
**The file that says how to validate this repo was one an agent could not
|
|
92
|
+
fix.** Measured on the same install as below: setup inferred `pnpm test`,
|
|
93
|
+
which in that repo is bare `vitest` — watch mode, it never exits, and it would
|
|
94
|
+
have hung every agent handed to it. The session that *discovered* that could
|
|
95
|
+
not repair the file that said it. It produced a diff, then a heredoc for the
|
|
96
|
+
operator to paste, then explained why it would not route around its own gate.
|
|
97
|
+
It was right not to. The gate was wrong.
|
|
98
|
+
|
|
99
|
+
So the shipped policy classes `.tyran/config.yaml` `AUTO`. It is mostly a
|
|
100
|
+
description of the repository — package manager, validation commands, shared
|
|
101
|
+
zones — and the agent that finds it wrong is what is best placed to correct it.
|
|
102
|
+
|
|
103
|
+
The cost is real and is now stated in all four places a user might read
|
|
104
|
+
(`templates/policies/autonomy.yaml`, `docs/configuration.md`,
|
|
105
|
+
`docs/policy-gate.md`, `docs/self-improvement.md`), because an unstated cost is
|
|
106
|
+
a false guarantee: **`autonomy:` lives in this file too, so an agent can raise
|
|
107
|
+
its own deployment class from P1 to P3 and then push to main.** What remains is
|
|
108
|
+
weaker and is said as such — nothing *infers* a raise, and a raise is a diff in
|
|
109
|
+
a committed file with its provenance beside it. Note that `docs/policy-gate.md`
|
|
110
|
+
had already measured this exact escalation happening *under* GATED, in an
|
|
111
|
+
unattended main loop, wherever `Write` is allow-listed; GATED was buying less
|
|
112
|
+
here than it looked like it was buying.
|
|
113
|
+
|
|
114
|
+
The push gate's own refusal named the old class too, and naming a class there
|
|
115
|
+
was the underlying mistake rather than naming the wrong one: the text is
|
|
116
|
+
per-repo configuration, so any class it prints goes stale the moment somebody
|
|
117
|
+
reclassifies the file. It now says the policy decides and names nothing, and
|
|
118
|
+
the test asserts the *absence* of a class claim instead of pinning a string
|
|
119
|
+
that has already been wrong once.
|
|
120
|
+
|
|
121
|
+
Two claims that had gone false are corrected rather than left standing:
|
|
122
|
+
`README.md`'s "the config file holding it is GATED, not KERNEL" and
|
|
123
|
+
`docs/configuration.md`'s "Tyran never raises it on its own — that path is
|
|
124
|
+
blocked by the policy hook". A test now pins the class *and* pins that the
|
|
125
|
+
template still spells out what it gives up, because flipping it back is a
|
|
126
|
+
one-word edit nobody would notice in review.
|
|
127
|
+
|
|
128
|
+
### Setup no longer locks the repository it is setting up
|
|
129
|
+
|
|
130
|
+
**`/tyran:setup` created `.tyran/config.yaml` and stopped, and that one
|
|
131
|
+
missing file made the repository unwritable.** The policy gate is silent in a
|
|
132
|
+
repo with no `.tyran/` directory and refuses every write in a repo that has
|
|
133
|
+
one without `.tyran/policies/autonomy.yaml` under it. Both halves are right;
|
|
134
|
+
their seam was not. Setup's own first command moved a fresh repo from
|
|
135
|
+
"unmanaged" to "refuses everything" — including the write that would have
|
|
136
|
+
installed the missing policy. Measured on a real install: the session ended
|
|
137
|
+
with the operator being handed a `mkdir` and a `cp` to run by hand, in the
|
|
138
|
+
middle of a one-command setup.
|
|
139
|
+
|
|
140
|
+
`scan-repo.mjs` now installs the policy from the shipped template **before**
|
|
141
|
+
it writes the config, and removes what it created if it cannot, so a failed
|
|
142
|
+
bootstrap cannot leave behind the exact state it exists to prevent. A repo
|
|
143
|
+
from before this change is repaired with `--ensure-policy`, which touches
|
|
144
|
+
nothing else.
|
|
145
|
+
|
|
146
|
+
That is bootstrap, not a loop authorizing itself, and the difference is
|
|
147
|
+
mechanical rather than a matter of intent: it only ever creates — an existing
|
|
148
|
+
policy is never read, merged or overwritten — and what it writes is the
|
|
149
|
+
shipped template byte for byte, the strictest default Tyran has. No input
|
|
150
|
+
makes it emit something weaker. Editing the file afterwards is human-only,
|
|
151
|
+
enforced exactly as before. Three tests pin the properties that make that
|
|
152
|
+
sentence true rather than aspirational: byte-identity with the template, an
|
|
153
|
+
untouched hand-written policy across setup and repair, and no `.tyran/` left
|
|
154
|
+
on disk when the install fails.
|
|
155
|
+
|
|
156
|
+
Two smaller things the same incident exposed. `doctor`'s `policy-missing`
|
|
157
|
+
finding was severity `info` — a repository where every tool call is denied,
|
|
158
|
+
reported as a note — and its suggested fix was a `cp` naming the policy path,
|
|
159
|
+
which the gate refuses when an agent runs it; it is now an `error` carrying a
|
|
160
|
+
command that works. And the documented `schema.mjs validate policy
|
|
161
|
+
.tyran/policies/…` line is one a **human** runs: inside a session it names a
|
|
162
|
+
path under `.tyran/policies/**` and is refused like any other. `doctor --state
|
|
163
|
+
--dir .tyran` validates the same file and names only the directory. The docs
|
|
164
|
+
say so now, and `/tyran:setup` runs the latter.
|
|
165
|
+
|
|
166
|
+
## 0.1.0 — 2026-07-27
|
|
4
167
|
|
|
5
168
|
### Six protocol skills, and the budget raised once to pay for them
|
|
6
169
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
|
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
|
|
162
|
-
.tyran/
|
|
163
|
-
|
|
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
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
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
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
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
|
-
|
|
351
|
-
|
|
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
|
-
> **
|
|
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
|
|
369
|
-
>
|
|
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](
|
|
378
|
-
- 🧰 [Skills and agents](
|
|
379
|
-
- ⚙️ [Configuration](
|
|
380
|
-
- 🎭 [The roster and model routing](
|
|
381
|
-
- 🏛️ [Architecture](
|
|
382
|
-
- 📜 [Journal reference](
|
|
383
|
-
- 🧾 [Projections](
|
|
384
|
-
- 🩺 [Doctor](
|
|
385
|
-
- 🪝 [Hook runtime](
|
|
386
|
-
- 🧾 [Evidence gate](
|
|
387
|
-
- 🛡️ [Policy gate](
|
|
388
|
-
- 🧠 [Self-improvement](
|
|
389
|
-
- ❓ [FAQ](
|
|
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
|
|
410
|
-
|
|
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}\`,
|
|
1346
|
-
'
|
|
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.
|
|
3
|
+
"version": "0.1.2",
|
|
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": {
|
package/scripts/doctor.mjs
CHANGED
|
@@ -49,6 +49,7 @@ import {
|
|
|
49
49
|
STATE_FILE,
|
|
50
50
|
} from './project.mjs';
|
|
51
51
|
import { classifyPath, normalizePath, validateFile, MANDATORY_KERNEL_PATHS } from './schema.mjs';
|
|
52
|
+
import { gitRunner } from './scan-repo.mjs';
|
|
52
53
|
|
|
53
54
|
/** Severity order is also the report order. `info` never fails the check. */
|
|
54
55
|
export const SEVERITIES = Object.freeze(['error', 'warning', 'info']);
|
|
@@ -175,7 +176,11 @@ export const SEVERITY_BY_CODE = Object.freeze(
|
|
|
175
176
|
'knowledge-invalid': 'error',
|
|
176
177
|
'knowledge-unreadable': 'error',
|
|
177
178
|
'knowledge-not-a-directory': 'warning',
|
|
178
|
-
|
|
179
|
+
// Not `info`, which is what it was: with `.tyran/` on disk and no policy
|
|
180
|
+
// under it the gate refuses every write in the repository. A severity that
|
|
181
|
+
// does not fail the check reports a locked-out repo as a note.
|
|
182
|
+
'tyran-dir-untracked': 'warning',
|
|
183
|
+
'policy-missing': 'error',
|
|
179
184
|
'policy-invalid': 'error',
|
|
180
185
|
'policy-unreadable': 'error',
|
|
181
186
|
'policies-unreadable': 'error',
|
|
@@ -980,7 +985,31 @@ function policyFindings(path, repoRoot) {
|
|
|
980
985
|
* Run every state check. Pure with respect to time: `now` is either given
|
|
981
986
|
* or taken from each journal's last event, never from the clock.
|
|
982
987
|
*/
|
|
983
|
-
|
|
988
|
+
/**
|
|
989
|
+
* Is `.tyran/` committed? The one Tyran failure that is completely silent.
|
|
990
|
+
*
|
|
991
|
+
* `git worktree add` carries TRACKED files only, and the policy gate is
|
|
992
|
+
* deliberately silent in a repository with no `.tyran/` directory. Put those
|
|
993
|
+
* two together and an uncommitted `.tyran/` means every worktree the conductor
|
|
994
|
+
* creates runs with no autonomy class and no path classes — nothing fails,
|
|
995
|
+
* nothing is refused, the boundary is simply absent in the one place the most
|
|
996
|
+
* agents run. Measured on a real install: four worktrees, four ungated
|
|
997
|
+
* implementers, and the operator had no way to see it.
|
|
998
|
+
*
|
|
999
|
+
* Returns null when git cannot answer. The distinction matters exactly as it
|
|
1000
|
+
* does in `detectPackageManager`: "this is not a git repository" is not
|
|
1001
|
+
* evidence that a file is untracked, and reporting it as such would fire on
|
|
1002
|
+
* every temp directory and every fresh `git init`.
|
|
1003
|
+
*/
|
|
1004
|
+
export function untrackedTyranDir(repoRoot, run) {
|
|
1005
|
+
if (run(['rev-parse', '--is-inside-work-tree']).trim() !== 'true') return null;
|
|
1006
|
+
// `ls-files` over the directory: any tracked file under it means the tree
|
|
1007
|
+
// travels with a worktree, which is the property being checked. Asking about
|
|
1008
|
+
// config.yaml alone would pass a repo that committed only the policy.
|
|
1009
|
+
return run(['ls-files', '--', '.tyran']).trim() === '';
|
|
1010
|
+
}
|
|
1011
|
+
|
|
1012
|
+
export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAULT_STALE_HOURS, run = null } = {}) {
|
|
984
1013
|
const root = resolve(dir);
|
|
985
1014
|
if (!existsSync(root)) {
|
|
986
1015
|
return summarize(dir, [finding('no-state-dir', show(dir), 'no Tyran state directory here — nothing to check')], [
|
|
@@ -1009,6 +1038,21 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1009
1038
|
checked.push('config.yaml: absent');
|
|
1010
1039
|
}
|
|
1011
1040
|
|
|
1041
|
+
const untracked = untrackedTyranDir(repoRoot, run ?? gitRunner(repoRoot));
|
|
1042
|
+
if (untracked === true) {
|
|
1043
|
+
findings.push(
|
|
1044
|
+
finding(
|
|
1045
|
+
'tyran-dir-untracked',
|
|
1046
|
+
show(dir),
|
|
1047
|
+
'nothing under .tyran/ is tracked by git — `git worktree add` carries tracked files only, and ' +
|
|
1048
|
+
'the policy gate is silent in a repo with no .tyran/, so every worktree runs with no autonomy ' +
|
|
1049
|
+
'class and no path classes. Nothing fails; the boundary is absent where the most agents run',
|
|
1050
|
+
`git add ${sq(dir)} && git commit -m 'chore: adopt Tyran'`,
|
|
1051
|
+
),
|
|
1052
|
+
);
|
|
1053
|
+
}
|
|
1054
|
+
checked.push(`.tyran/ tracked by git: ${untracked === null ? 'unknown (not a git work tree)' : !untracked}`);
|
|
1055
|
+
|
|
1012
1056
|
const knowledge = yamlFilesIn(join(dir, 'knowledge'), 'knowledge');
|
|
1013
1057
|
findings.push(...knowledge.findings);
|
|
1014
1058
|
for (const file of knowledge.files) findings.push(...checkSchemaFile('knowledge', file).findings);
|
|
@@ -1022,8 +1066,11 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1022
1066
|
finding(
|
|
1023
1067
|
'policy-missing',
|
|
1024
1068
|
show(join(dir, 'policies')),
|
|
1025
|
-
'no autonomy policy
|
|
1026
|
-
|
|
1069
|
+
'no autonomy policy, in a repo that HAS a .tyran/ directory — the policy gate fails closed on ' +
|
|
1070
|
+
'exactly this state, so every write in every session is refused until the file exists. It is not ' +
|
|
1071
|
+
'a missing nicety; the repository is unusable',
|
|
1072
|
+
`node scripts/scan-repo.mjs --dir ${sq(repoRoot)} --ensure-policy # installs the shipped template; ` +
|
|
1073
|
+
'never overwrites a policy you wrote',
|
|
1027
1074
|
),
|
|
1028
1075
|
);
|
|
1029
1076
|
}
|
|
@@ -1218,8 +1265,13 @@ function main() {
|
|
|
1218
1265
|
if (err instanceof UsageError) {
|
|
1219
1266
|
console.error(
|
|
1220
1267
|
'usage: doctor.mjs --state [--dir <.tyran>] [--json] [--now <iso>] [--stale-hours <n>]\n' +
|
|
1221
|
-
' --
|
|
1222
|
-
'
|
|
1268
|
+
' doctor.mjs --hooks [--plugin-root <dir>] [--json]\n' +
|
|
1269
|
+
'\n' +
|
|
1270
|
+
' A mode is REQUIRED: `--state` asks whether the record of the work is\n' +
|
|
1271
|
+
' consistent, `--hooks` whether the gates can fire at all. They answer\n' +
|
|
1272
|
+
' different questions, and a bare invocation would have to pick one\n' +
|
|
1273
|
+
' silently. This text said `--state is the only mode today` long after\n' +
|
|
1274
|
+
' `--hooks` shipped, which sent readers looking for a flag they had.',
|
|
1223
1275
|
);
|
|
1224
1276
|
process.exit(2);
|
|
1225
1277
|
}
|
package/scripts/scan-repo.mjs
CHANGED
|
@@ -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
|
-
|
|
94
|
-
|
|
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 =
|
|
125
|
-
|
|
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 {
|
package/scripts/yaml-lite.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
}
|
package/skills/run/SKILL.md
CHANGED
|
@@ -236,6 +236,16 @@ 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 worktree without `.tyran/` is an UNGATED worktree.** `git worktree
|
|
240
|
+
add` carries tracked files only, so an uncommitted `.tyran/` does not
|
|
241
|
+
reach one — and the policy gate is deliberately silent in a repo that has
|
|
242
|
+
no `.tyran/` at all. The agents there then run with no autonomy class and
|
|
243
|
+
no path classes: nothing fails, the boundary is simply absent, in the one
|
|
244
|
+
place you are running the most agents. Measured on a real install: four
|
|
245
|
+
worktrees, four ungated implementers. So **check every worktree you
|
|
246
|
+
create** and, if `.tyran/` is missing, get it committed on the main
|
|
247
|
+
checkout first rather than copying it in — a copy makes four divergent
|
|
248
|
+
configs, which is the same defect one layer down.
|
|
239
249
|
- **Leases are files.** Every worktree and every heavy slot has
|
|
240
250
|
`.tyran/initiatives/<slug>/locks/<resource>.lease` holding holder,
|
|
241
251
|
purpose, story and expiry. A handoff BEGINS by taking the lease — an
|
package/skills/setup/SKILL.md
CHANGED
|
@@ -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
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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:
|
|
37
|
-
reason:
|
|
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
|