@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +296 -1
- package/README.md +52 -49
- package/hooks/scripts/policy-gate.mjs +228 -15
- package/hooks/scripts/secrets-gate.mjs +100 -6
- package/package.json +1 -1
- package/scripts/doctor.mjs +58 -6
- package/scripts/journal.mjs +47 -5
- package/scripts/scan-repo.mjs +304 -9
- package/scripts/yaml-lite.mjs +22 -1
- package/skills/run/SKILL.md +28 -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.4",
|
|
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.4",
|
|
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,301 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## 0.1.
|
|
3
|
+
## 0.1.4 — 2026-08-01
|
|
4
|
+
|
|
5
|
+
### The gate stopped refusing Claude Code's own memory
|
|
6
|
+
|
|
7
|
+
Adopting Tyran in a repo made the policy gate refuse the harness's OWN writes:
|
|
8
|
+
`Write` to `~/.claude/projects/<slug>/memory/*.md` came back "outside this
|
|
9
|
+
repository, class KERNEL". The memory store and the per-session scratchpad are
|
|
10
|
+
genuinely outside every repository, so `repoRelative` returned null and the
|
|
11
|
+
write matrix answered KERNEL — the same branch that correctly refuses writing
|
|
12
|
+
into somebody else's repo. The cost was that the assistant could no longer
|
|
13
|
+
persist what it learned while working in a Tyran repo, and a boundary that
|
|
14
|
+
blocks the tool's own bookkeeping is one its user turns off.
|
|
15
|
+
|
|
16
|
+
The gate now exempts exactly two locations, and only for the `main` thread:
|
|
17
|
+
`<config>/projects/<slug>/memory/` and `<tmp>/claude-<id>/`. Everything else
|
|
18
|
+
outside the repo is still KERNEL; the rest of the config dir — including
|
|
19
|
+
`settings.json`, which registers these very hooks — stays untouchable; and a
|
|
20
|
+
subagent is never exempted, because it has no business writing outside its
|
|
21
|
+
worktree. Bash never hit this: an out-of-repo token yields no finding, so
|
|
22
|
+
`echo > scratch` was already allowed — the refusal lived only on the
|
|
23
|
+
file-writing tools, which is the asymmetry a user actually meets.
|
|
24
|
+
|
|
25
|
+
### npm publishes on a pushed tag
|
|
26
|
+
|
|
27
|
+
`npm-publish.yml` now also triggers on a pushed `v*` tag, not only on a
|
|
28
|
+
published GitHub release. npm served 0.1.0 while the marketplace was three
|
|
29
|
+
releases ahead, because the manual release step was skipped for 0.1.1, 0.1.2
|
|
30
|
+
and 0.1.3; a release step a human has to remember is one that drifts. The
|
|
31
|
+
version-must-match-the-tag guard runs for both triggers, and npm refuses a
|
|
32
|
+
duplicate version, so the two are idempotent.
|
|
33
|
+
|
|
34
|
+
## 0.1.3 — 2026-07-29
|
|
35
|
+
|
|
36
|
+
From two independent field reports on complete initiatives — one M, one L —
|
|
37
|
+
run on 0.1.1 and 0.1.2. Five of the reported items are fixed; the rest are
|
|
38
|
+
recorded here as open, with the reason.
|
|
39
|
+
|
|
40
|
+
### A git worktree is the same repository
|
|
41
|
+
|
|
42
|
+
Two reports described **opposite** failures with one cause: the policy gate
|
|
43
|
+
read "the repository" as "this directory tree", and a worktree is neither
|
|
44
|
+
inside it nor a different repository.
|
|
45
|
+
|
|
46
|
+
- **Silent.** A session running *in* a worktree found no `.tyran/` there — the
|
|
47
|
+
directory is committed data and `git worktree add` gives a fresh checkout —
|
|
48
|
+
so the gate concluded Tyran had not been adopted and said nothing. Four
|
|
49
|
+
worktrees, four implementers with no autonomy class and no path classes, and
|
|
50
|
+
`git push origin main` passing at every deployment class.
|
|
51
|
+
- **Loud.** A session in the main checkout writing *into* a worktree got
|
|
52
|
+
`normalizePath → null → KERNEL`: every `Edit` refused as "outside this
|
|
53
|
+
repository", while `skills/run/SKILL.md` rule 7 *requires* a worktree per
|
|
54
|
+
agent. Five agents hit it in one initiative and all rerouted through `Bash`
|
|
55
|
+
heredocs — a channel the gate does not class at all. A refusal that moves
|
|
56
|
+
work somewhere less visible is worse than no refusal, and this one was the
|
|
57
|
+
plugin contradicting itself.
|
|
58
|
+
|
|
59
|
+
The gate now asks which repository a path belongs to. Detection is pure
|
|
60
|
+
filesystem — a linked worktree's `.git` is a *file* holding `gitdir:` — so the
|
|
61
|
+
write path still runs no child processes. Policy and config are inherited from
|
|
62
|
+
the main checkout, and the test is **identity, not proximity**: both sides must
|
|
63
|
+
resolve to the same main checkout, so a path in a different repository is still
|
|
64
|
+
KERNEL. Three mutants were installed and killed, including one that survived
|
|
65
|
+
the first version of the push test — it refused for the wrong reason and the
|
|
66
|
+
assertion could not tell.
|
|
67
|
+
|
|
68
|
+
### `git stash push` was read as `git push`
|
|
69
|
+
|
|
70
|
+
`words.has('push')` was true when the word appeared anywhere in the segment, so
|
|
71
|
+
`git stash push --staged -m "conductor: ..."` — purely local — was classified as
|
|
72
|
+
a publish. The remote was then read as the token after the word: `conductor` out
|
|
73
|
+
of the message, or `2` out of a `2>&1`. The refusal told the operator to run
|
|
74
|
+
`git remote set-head conductor -a`, which cannot succeed, about a repository
|
|
75
|
+
whose default branch was recorded all along.
|
|
76
|
+
|
|
77
|
+
The cost was not one bad refusal: rule 7 *requires* addressed stashes to protect
|
|
78
|
+
other windows' work, so the gate refused the safe half of a workflow the plugin
|
|
79
|
+
mandates and pushed agents toward the deprecated positional form. `git remote
|
|
80
|
+
add` and `git worktree add` had the same shape against the `add` rule — and
|
|
81
|
+
`worktree add` is what rule 7 tells every parallel agent to run.
|
|
82
|
+
|
|
83
|
+
Classification now resolves the **subcommand slot**. It is not a pure narrowing:
|
|
84
|
+
`git subtree push` publishes for real and its verb is the second word, so
|
|
85
|
+
namespace subcommands forward their verb. Dropping that would have traded a
|
|
86
|
+
false positive for a false negative on a genuine push.
|
|
87
|
+
|
|
88
|
+
### `journal.mjs append` issues the id it used to demand
|
|
89
|
+
|
|
90
|
+
`skills/run/SKILL.md` says IDs never come from memory, because after a
|
|
91
|
+
compaction memory hands out the same number twice — and `append` then *rejected*
|
|
92
|
+
a missing `data.id`, leaving the conductor to remember a separate `next-id`
|
|
93
|
+
call. Measured: 12 decision IDs hand-assigned from memory in one initiative,
|
|
94
|
+
the exact failure the rule names, with nothing objecting. Both reports raised
|
|
95
|
+
it independently. An explicit id still wins.
|
|
96
|
+
|
|
97
|
+
Two errors that could only be answered by grepping the plugin's source now
|
|
98
|
+
answer themselves: a rejected `ev` lists the closed set, and a missing `data`
|
|
99
|
+
key names the whole contract for that event rather than the first key checked.
|
|
100
|
+
`--help` prints the per-event table.
|
|
101
|
+
|
|
102
|
+
### Worktrees, in the conductor's own words
|
|
103
|
+
|
|
104
|
+
Rule 7 said "a git worktree per agent" and stopped. A fresh worktree has no
|
|
105
|
+
dependencies, so every validation command exits 127 and the evidence contract
|
|
106
|
+
cannot be satisfied by construction. The rule now says to link the main
|
|
107
|
+
checkout's dependency directory — safe precisely because the manifest and
|
|
108
|
+
lockfile are already a shared zone nobody may edit — and notes that
|
|
109
|
+
`.tyran/state/**` exists only in the main checkout.
|
|
110
|
+
|
|
111
|
+
Also: the conductor is told it is notified when a subagent finishes and should
|
|
112
|
+
not poll. On a real run most polled checkpoints fired after the agent had
|
|
113
|
+
already reported, and the operator watched the conductor disown dozens of stale
|
|
114
|
+
notifications.
|
|
115
|
+
|
|
116
|
+
### Open, and why
|
|
117
|
+
|
|
118
|
+
- **No lease on the checkout.** Two agents in one checkout is the failure rule 7
|
|
119
|
+
exists to prevent, and nothing enforces it; leases cover the heavy slot and
|
|
120
|
+
not the working tree. The reporting retro reached the same conclusion and
|
|
121
|
+
refused to patch it locally, correctly — the only real fix is a hook, and
|
|
122
|
+
`hooks/**` is KERNEL, so no session can build one. It needs a design pass,
|
|
123
|
+
not a hurried one.
|
|
124
|
+
- **The gate matches command TEXT**, so `ls -1 .npmrc` is refused as a
|
|
125
|
+
credential read though it reads nothing, and the scratch directory a `GATED`
|
|
126
|
+
refusal tells an agent to write its diff into is refused as outside the repo.
|
|
127
|
+
The second is self-defeating and should be fixed; both are refusal semantics.
|
|
128
|
+
- **`doctor` does not enumerate worktrees or cross-check `RELEASED` leases**
|
|
129
|
+
against resources that still exist. A field run lost a validation baseline to
|
|
130
|
+
32,243 phantom lint errors from leftover worktrees.
|
|
131
|
+
- **Forge detection.** Tyran assumes GitHub; on Bitbucket the default terminal
|
|
132
|
+
step of the default autonomy class has no defined path, and two agents each
|
|
133
|
+
rediscovered that.
|
|
134
|
+
|
|
135
|
+
## 0.1.2 — 2026-07-29
|
|
136
|
+
|
|
137
|
+
From a field report on a real 0.1.1 install. Every item below is a failure
|
|
138
|
+
somebody hit, not one anybody predicted.
|
|
139
|
+
|
|
140
|
+
### The worktree with no boundary
|
|
141
|
+
|
|
142
|
+
**`git worktree add` carries tracked files only, and the policy gate is
|
|
143
|
+
deliberately silent in a repo with no `.tyran/`.** Put those together and an
|
|
144
|
+
uncommitted `.tyran/` means every worktree the conductor creates has no config
|
|
145
|
+
and no policy — so the agents there run with **no autonomy class and no path
|
|
146
|
+
classes at all**. Nothing is refused, nothing fails, and `git push origin main`
|
|
147
|
+
returns `PASS` on line 1213 of the gate. Measured: four worktrees, four ungated
|
|
148
|
+
implementers, and no way for the operator to see it.
|
|
149
|
+
|
|
150
|
+
This is the worst kind of defect this project can have, because Tyran's whole
|
|
151
|
+
argument is that the boundary is a mechanism rather than a promise — and here
|
|
152
|
+
it was absent precisely where the most agents run.
|
|
153
|
+
|
|
154
|
+
Three changes, none of which touch the gate:
|
|
155
|
+
|
|
156
|
+
- `doctor --state` gains **`tyran-dir-untracked`** (warning): git is asked
|
|
157
|
+
whether anything under `.tyran/` is tracked. It returns *no answer* outside a
|
|
158
|
+
work tree rather than inventing one, the same discipline the lockfile rule
|
|
159
|
+
below uses;
|
|
160
|
+
- `/tyran:setup` now ends by asking for the commit, **with the reason**, rather
|
|
161
|
+
than leaving `.tyran/` sitting untracked;
|
|
162
|
+
- the conductor treats a worktree without `.tyran/` as a precondition failure,
|
|
163
|
+
and is told to fix it by committing on the main checkout — not by copying the
|
|
164
|
+
file in, which just makes four divergent configs one layer down.
|
|
165
|
+
|
|
166
|
+
### Two inferences that produced a broken gate
|
|
167
|
+
|
|
168
|
+
**A validation command that watches does not fail an agent, it hangs it.**
|
|
169
|
+
Setup wrote `pnpm test` into a repo whose `test` script is bare `vitest` —
|
|
170
|
+
watch mode, no output, no timeout, a session that simply stops. `detectValidation`
|
|
171
|
+
now reroutes to a run-once variant (`test:run`, `test:ci`, `test:once`) and, if
|
|
172
|
+
there is none, **leaves the command out** and flags the config rather than
|
|
173
|
+
writing a booby trap. The rule is deliberately narrow — `jest` runs once by
|
|
174
|
+
default and is not treated as a watcher — because a false positive here silently
|
|
175
|
+
drops a real test command.
|
|
176
|
+
|
|
177
|
+
**A lockfile on disk is not evidence that it is the repo's lockfile.** The same
|
|
178
|
+
install had `pnpm-lock.yaml` gitignored and untracked alongside the tracked
|
|
179
|
+
`package-lock.json` that its deploy actually builds from, and `.gitignore` said
|
|
180
|
+
so in words. Picking by disk order chose pnpm, and then every single validation
|
|
181
|
+
command was wrong. `detectPackageManager` now asks git which lockfiles are
|
|
182
|
+
tracked and says which one it rejected. An empty `git ls-files` means git could
|
|
183
|
+
not answer and changes nothing — "not a git repo" is not evidence that a file is
|
|
184
|
+
ignored.
|
|
185
|
+
|
|
186
|
+
Both replay clean against the repository that produced them.
|
|
187
|
+
|
|
188
|
+
### Errors that named the wrong cause
|
|
189
|
+
|
|
190
|
+
`yaml-lite` answered every unbalanced quote with *"quote the whole value if it
|
|
191
|
+
contains an apostrophe"*. An operator writing a long `source:` as a multi-line
|
|
192
|
+
double-quoted string was sent hunting an apostrophe that did not exist, three
|
|
193
|
+
times. A value that opens a quote and never closes it now says exactly that,
|
|
194
|
+
and says the subset has no multi-line scalars. The apostrophe advice survives
|
|
195
|
+
only on the case it is actually about.
|
|
196
|
+
|
|
197
|
+
`doctor.mjs` with no flag printed *"--state is the only mode today"* long after
|
|
198
|
+
`--hooks` shipped, sending readers to look for a flag they already had.
|
|
199
|
+
|
|
200
|
+
The generated `config.yaml` header now states the YAML subset and asks for the
|
|
201
|
+
commit, since both traps are sprung by hand-editing a file whose constraints
|
|
202
|
+
were documented somewhere else.
|
|
203
|
+
|
|
204
|
+
### Still open, deliberately
|
|
205
|
+
|
|
206
|
+
The report also found that the gate matches on command TEXT, so `ls -1 .npmrc`
|
|
207
|
+
is refused as a credential read though it reads nothing, and that a `GATED`
|
|
208
|
+
refusal tells an agent to write a diff for the operator while `outside this
|
|
209
|
+
repository is never autonomous` refuses the scratch directory that is the
|
|
210
|
+
obvious place to put it. That second one is self-defeating and worth fixing.
|
|
211
|
+
Both are changes to refusal semantics in a KERNEL file and are not being made
|
|
212
|
+
in the same pass as everything above.
|
|
213
|
+
|
|
214
|
+
## 0.1.1 — 2026-07-29
|
|
215
|
+
|
|
216
|
+
Both entries below come from one install of 0.1.0 on a real repository. The
|
|
217
|
+
version is bumped rather than folded into 0.1.0 because `claude plugin update`
|
|
218
|
+
compares **versions**, not commits: with the manifest left at 0.1.0 it reports
|
|
219
|
+
"already at the latest version" and users never receive the fix.
|
|
220
|
+
|
|
221
|
+
### `.tyran/config.yaml` is AUTO, and what that costs is written down
|
|
222
|
+
|
|
223
|
+
**The file that says how to validate this repo was one an agent could not
|
|
224
|
+
fix.** Measured on the same install as below: setup inferred `pnpm test`,
|
|
225
|
+
which in that repo is bare `vitest` — watch mode, it never exits, and it would
|
|
226
|
+
have hung every agent handed to it. The session that *discovered* that could
|
|
227
|
+
not repair the file that said it. It produced a diff, then a heredoc for the
|
|
228
|
+
operator to paste, then explained why it would not route around its own gate.
|
|
229
|
+
It was right not to. The gate was wrong.
|
|
230
|
+
|
|
231
|
+
So the shipped policy classes `.tyran/config.yaml` `AUTO`. It is mostly a
|
|
232
|
+
description of the repository — package manager, validation commands, shared
|
|
233
|
+
zones — and the agent that finds it wrong is what is best placed to correct it.
|
|
234
|
+
|
|
235
|
+
The cost is real and is now stated in all four places a user might read
|
|
236
|
+
(`templates/policies/autonomy.yaml`, `docs/configuration.md`,
|
|
237
|
+
`docs/policy-gate.md`, `docs/self-improvement.md`), because an unstated cost is
|
|
238
|
+
a false guarantee: **`autonomy:` lives in this file too, so an agent can raise
|
|
239
|
+
its own deployment class from P1 to P3 and then push to main.** What remains is
|
|
240
|
+
weaker and is said as such — nothing *infers* a raise, and a raise is a diff in
|
|
241
|
+
a committed file with its provenance beside it. Note that `docs/policy-gate.md`
|
|
242
|
+
had already measured this exact escalation happening *under* GATED, in an
|
|
243
|
+
unattended main loop, wherever `Write` is allow-listed; GATED was buying less
|
|
244
|
+
here than it looked like it was buying.
|
|
245
|
+
|
|
246
|
+
The push gate's own refusal named the old class too, and naming a class there
|
|
247
|
+
was the underlying mistake rather than naming the wrong one: the text is
|
|
248
|
+
per-repo configuration, so any class it prints goes stale the moment somebody
|
|
249
|
+
reclassifies the file. It now says the policy decides and names nothing, and
|
|
250
|
+
the test asserts the *absence* of a class claim instead of pinning a string
|
|
251
|
+
that has already been wrong once.
|
|
252
|
+
|
|
253
|
+
Two claims that had gone false are corrected rather than left standing:
|
|
254
|
+
`README.md`'s "the config file holding it is GATED, not KERNEL" and
|
|
255
|
+
`docs/configuration.md`'s "Tyran never raises it on its own — that path is
|
|
256
|
+
blocked by the policy hook". A test now pins the class *and* pins that the
|
|
257
|
+
template still spells out what it gives up, because flipping it back is a
|
|
258
|
+
one-word edit nobody would notice in review.
|
|
259
|
+
|
|
260
|
+
### Setup no longer locks the repository it is setting up
|
|
261
|
+
|
|
262
|
+
**`/tyran:setup` created `.tyran/config.yaml` and stopped, and that one
|
|
263
|
+
missing file made the repository unwritable.** The policy gate is silent in a
|
|
264
|
+
repo with no `.tyran/` directory and refuses every write in a repo that has
|
|
265
|
+
one without `.tyran/policies/autonomy.yaml` under it. Both halves are right;
|
|
266
|
+
their seam was not. Setup's own first command moved a fresh repo from
|
|
267
|
+
"unmanaged" to "refuses everything" — including the write that would have
|
|
268
|
+
installed the missing policy. Measured on a real install: the session ended
|
|
269
|
+
with the operator being handed a `mkdir` and a `cp` to run by hand, in the
|
|
270
|
+
middle of a one-command setup.
|
|
271
|
+
|
|
272
|
+
`scan-repo.mjs` now installs the policy from the shipped template **before**
|
|
273
|
+
it writes the config, and removes what it created if it cannot, so a failed
|
|
274
|
+
bootstrap cannot leave behind the exact state it exists to prevent. A repo
|
|
275
|
+
from before this change is repaired with `--ensure-policy`, which touches
|
|
276
|
+
nothing else.
|
|
277
|
+
|
|
278
|
+
That is bootstrap, not a loop authorizing itself, and the difference is
|
|
279
|
+
mechanical rather than a matter of intent: it only ever creates — an existing
|
|
280
|
+
policy is never read, merged or overwritten — and what it writes is the
|
|
281
|
+
shipped template byte for byte, the strictest default Tyran has. No input
|
|
282
|
+
makes it emit something weaker. Editing the file afterwards is human-only,
|
|
283
|
+
enforced exactly as before. Three tests pin the properties that make that
|
|
284
|
+
sentence true rather than aspirational: byte-identity with the template, an
|
|
285
|
+
untouched hand-written policy across setup and repair, and no `.tyran/` left
|
|
286
|
+
on disk when the install fails.
|
|
287
|
+
|
|
288
|
+
Two smaller things the same incident exposed. `doctor`'s `policy-missing`
|
|
289
|
+
finding was severity `info` — a repository where every tool call is denied,
|
|
290
|
+
reported as a note — and its suggested fix was a `cp` naming the policy path,
|
|
291
|
+
which the gate refuses when an agent runs it; it is now an `error` carrying a
|
|
292
|
+
command that works. And the documented `schema.mjs validate policy
|
|
293
|
+
.tyran/policies/…` line is one a **human** runs: inside a session it names a
|
|
294
|
+
path under `.tyran/policies/**` and is refused like any other. `doctor --state
|
|
295
|
+
--dir .tyran` validates the same file and names only the directory. The docs
|
|
296
|
+
say so now, and `/tyran:setup` runs the latter.
|
|
297
|
+
|
|
298
|
+
## 0.1.0 — 2026-07-27
|
|
4
299
|
|
|
5
300
|
### Six protocol skills, and the budget raised once to pay for them
|
|
6
301
|
|
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
|
|