@jjanczur/tyran 0.1.13 → 0.1.17
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 +226 -0
- package/README.md +7 -1
- package/agents/implementer.md +15 -3
- package/agents/retro.md +17 -2
- package/agents/reviewer.md +7 -0
- package/bin/tyran.mjs +8 -0
- package/hooks/scripts/policy-gate.mjs +374 -8
- package/hooks/scripts/session-start.mjs +69 -2
- package/package.json +1 -1
- package/scripts/answer.mjs +896 -0
- package/scripts/board.mjs +4 -1
- package/scripts/doctor.mjs +169 -0
- package/scripts/journal.mjs +79 -1
- package/scripts/keepawake.mjs +187 -0
- package/scripts/mistakes.mjs +1005 -0
- package/scripts/overnight.mjs +92 -5
- package/scripts/project.mjs +15 -3
- package/scripts/scan-repo.mjs +107 -1
- package/scripts/schema.mjs +10 -1
- package/scripts/tiers.mjs +17 -0
- package/skills/retro/SKILL.md +80 -1
- package/skills/run/SKILL.md +33 -7
- package/skills/setup/SKILL.md +27 -1
- package/templates/MISTAKES.md +39 -0
- package/templates/config.yaml +5 -0
- package/templates/policies/autonomy.yaml +18 -0
|
@@ -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.17",
|
|
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.17",
|
|
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,5 +1,231 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.17 — 2026-08-14
|
|
4
|
+
|
|
5
|
+
### A race test that picked a winner
|
|
6
|
+
|
|
7
|
+
`two apply runs at once cannot both close one ask` accepted only two of the
|
|
8
|
+
three exits its own race can produce. On a runner slow enough to serialise
|
|
9
|
+
the two spawns, the first closes the queue and the second finds it empty and
|
|
10
|
+
exits 1 — correct behaviour, asserted as a failure. It passed locally and in
|
|
11
|
+
the PR checks and failed in the publish job, which is where a timing
|
|
12
|
+
assumption usually surfaces, and it kept 0.1.15 and 0.1.16 off npm although
|
|
13
|
+
both are merged and tagged.
|
|
14
|
+
|
|
15
|
+
All three exits are now accepted, and the guarantee is asserted where it
|
|
16
|
+
holds regardless of who won: no ask closed twice and no question closed by
|
|
17
|
+
two gates, checked while the racing runs are the only writers, then
|
|
18
|
+
completeness after one sequential settling run. Dropping the sitting lock
|
|
19
|
+
still fails the test.
|
|
20
|
+
|
|
21
|
+
## 0.1.16 — 2026-08-14
|
|
22
|
+
|
|
23
|
+
### `cat hooks/…` was refused while `Read` handed you the same bytes
|
|
24
|
+
|
|
25
|
+
Measured on the shipped 0.1.15 gate, on one file under `hooks/**`: `Read` passes,
|
|
26
|
+
and `cat`, `grep -n`, `wc -l` and `node --check` on that same file all **deny**.
|
|
27
|
+
The bytes were one tool call away in every case, so the refusal protected
|
|
28
|
+
nothing — and it was not consistent with itself either: `git log --oneline --
|
|
29
|
+
hooks/` passed all along, because a bare directory token names no file to
|
|
30
|
+
classify, while `wc -l` on a file inside it did not. The cost was four
|
|
31
|
+
interrupted tool calls in one session for the author, every one of them while
|
|
32
|
+
reading the gate being worked on.
|
|
33
|
+
|
|
34
|
+
The rule this release encodes instead: **the shell must not become a second
|
|
35
|
+
route to something the `Read` tool already refuses.** For `.env` that symmetry
|
|
36
|
+
is load-bearing and is untouched — `Read` denies *and* `grep` denies, because
|
|
37
|
+
the measured incident behind that rule is a refused `Read .env` followed by
|
|
38
|
+
`Bash: grep` in the very next tool call. Where `Read` is allowed, refusing the
|
|
39
|
+
shell buys nothing.
|
|
40
|
+
|
|
41
|
+
So on `hooks/**` and `.tyran/policies/**` — and only there — a read-only shell
|
|
42
|
+
command now passes. "Read-only" is matched on the **program and its flags**,
|
|
43
|
+
never on the program alone, because read-shaped programs have write-shaped
|
|
44
|
+
modes: `node --check FILE` passes and `node FILE` denies; `git log` passes and
|
|
45
|
+
`git log --output=FILE` denies, which was a real hole found in an earlier review
|
|
46
|
+
of this gate; `tail -n 5` passes and `tail -f` does not. An unrecognised flag
|
|
47
|
+
refuses, so the enumeration's incompleteness costs a false refusal and never a
|
|
48
|
+
pass. `sed` and `awk` are not on the list at all: their script argument is a
|
|
49
|
+
program with its own write commands, and reading it would need a second parser.
|
|
50
|
+
The raw command may contain none of ``< > $ ` ( ) { } &``, which is every
|
|
51
|
+
redirection spelling, command substitution, subshell and `&&` at once — checked
|
|
52
|
+
on the raw text, because the shared lexer *consumes* those characters as
|
|
53
|
+
separators and by the time a token exists the `>` is gone. `|` and `;` are fine,
|
|
54
|
+
since each composed segment still has to be an allowed reader.
|
|
55
|
+
|
|
56
|
+
What did not change: every credential shape denies for reads and writes alike;
|
|
57
|
+
`.claude/settings.json` and `.claude/settings.local.json` stay refused from a
|
|
58
|
+
shell in every mode, which is a deliberate narrowing rather than a consequence —
|
|
59
|
+
`Read` passes on the registry too, so the principle alone would have admitted it,
|
|
60
|
+
and it is the one file from which every gate is switched off at once. One line
|
|
61
|
+
naming a readable path *and* a secret is still refused for the secret.
|
|
62
|
+
|
|
63
|
+
That last sentence needed a second check to stay true, and review found it out.
|
|
64
|
+
The exemption was decided on the **finding list**, which is computed from a
|
|
65
|
+
*stripped* copy of the command: `stripMessageArguments` removes a message-bearing
|
|
66
|
+
flag together with its argument, and non-literal tokens are dropped after that.
|
|
67
|
+
`-t` is `git commit --template` *and* a legal flag of `diff` and `cat`, so
|
|
68
|
+
`diff -t .env hooks/scripts/policy-gate.mjs` left a finding list naming only the
|
|
69
|
+
readable path, read as "read-only command on a readable path", and was exempted —
|
|
70
|
+
really publishing the file. Four shapes were measured deny-on-0.1.15 →
|
|
71
|
+
pass-before-the-fix: `diff -t SECRET FILE`, `grep --file=SECRET FILE`,
|
|
72
|
+
`grep -m SECRET FILE`, and `diff ~/SECRET FILE`, the last because a leading `~`
|
|
73
|
+
makes the token non-literal and it is dropped entirely. The exemption is now
|
|
74
|
+
refused when any word of the **raw** command is credential-shaped, tested with
|
|
75
|
+
the same `SECRET_READ_RULES` the findings use, and the refusal names that word
|
|
76
|
+
rather than offering a rewrite that cannot help. This is the invariant being
|
|
77
|
+
repaired, not a new capability: `diff -t .env src/app.js` publishes the same
|
|
78
|
+
bytes and always did, because it names no protected path at all. One false
|
|
79
|
+
refusal comes with it, in the safe direction — `git log --grep=.env -- FILE`
|
|
80
|
+
loses the exemption over a word in a search pattern.
|
|
81
|
+
|
|
82
|
+
The residual floor is stated in the refusal text and in `docs/policy-gate.md`
|
|
83
|
+
rather than implied: matching flags bounds what a command *says*, not what the
|
|
84
|
+
program *does*. An allowed reader can still be pointed at another program by
|
|
85
|
+
configuration this gate never reads — a `diff.external` driver or a pager in git
|
|
86
|
+
config, a `NODE_OPTIONS` carrying `--require`, a shell function shadowing `cat`.
|
|
87
|
+
That is the fifth entry in `SHELL_DECLARED_MISSES`. The sixth is one step
|
|
88
|
+
earlier: the program table is keyed on the **basename**, which is what makes
|
|
89
|
+
`/bin/cat` and `cat` one entry and also makes a repo-writable `src/cat` an
|
|
90
|
+
allowed reader. It is declared rather than closed, because closing it would
|
|
91
|
+
close nothing — a script with the path already inside it needs no allowed name
|
|
92
|
+
at all, which is the third entry.
|
|
93
|
+
|
|
94
|
+
## 0.1.15 — 2026-08-14
|
|
95
|
+
|
|
96
|
+
### Fifteen questions, ten minutes, and the swarm moves
|
|
97
|
+
|
|
98
|
+
An agent that hits a product decision no longer stops and waits for you. It
|
|
99
|
+
raises the question — `journal.mjs ask`, one command, which mints the id under
|
|
100
|
+
the journal's write lock so two agents asking at the same moment get two
|
|
101
|
+
questions rather than one — states what it recommends and what should ship if
|
|
102
|
+
nobody ever answers, and takes the next ticket. The question is a `gate` whose
|
|
103
|
+
`kind` IS its id, `Q-<n>`: the closed event set stays at 17, the board's
|
|
104
|
+
waiting-on-you queue already rendered it, and `answered` was already a pass
|
|
105
|
+
result. What was missing was an identity and a way in.
|
|
106
|
+
|
|
107
|
+
The way in is a text file. `tyran answer render` writes `.tyran/state/ANSWERS.md`
|
|
108
|
+
— every open question across every initiative, the ones with no recorded default
|
|
109
|
+
first, because those are the only ones where saying nothing has no safe outcome.
|
|
110
|
+
You type under `answer:`. **Blank accepts the recorded default**, verbatim, and
|
|
111
|
+
still records it as a decision; `-` leaves it for next time; anything else is your
|
|
112
|
+
answer in your own words. `tyran answer apply` folds them back as `decision` +
|
|
113
|
+
`gate result: answered` pairs — decision first, so a crash leaves a visible orphan
|
|
114
|
+
decision rather than a closed question whose answer was never written down — then
|
|
115
|
+
re-renders every projection and the board. It reads the question, the default and
|
|
116
|
+
the ticket back out of the journal, never out of the sheet, and it is
|
|
117
|
+
all-or-nothing: one unparseable block and nothing at all is appended, with the
|
|
118
|
+
line number.
|
|
119
|
+
|
|
120
|
+
Answering a question no longer needs the conductor to be awake. `SessionStart`
|
|
121
|
+
records the session id in `.tyran/state/conductor.json`, so `apply --resume` can
|
|
122
|
+
put the swarm back on it — and refuses while that session is still alive, because
|
|
123
|
+
two conductors on one journal is a hazard this repo has already paid for once.
|
|
124
|
+
|
|
125
|
+
One correction found while building it. Parking an asked ticket **hid** it: the
|
|
126
|
+
board checks a `ticket.status` override before the ask, so our own demo fixture
|
|
127
|
+
showed `waiting-operator (0)` with a question open — the fixture is corrected and
|
|
128
|
+
the skill now forbids the override.
|
|
129
|
+
|
|
130
|
+
Also: `question`, `recommendation`, `default` and `answer` are capped at 2000
|
|
131
|
+
codepoints (rejected, never truncated — historical oversizes stay warnings);
|
|
132
|
+
`STATE.md`'s open-gates table and the SessionStart probe now carry the question
|
|
133
|
+
text, so a resumed conductor sees *what* it asked and not merely that it is
|
|
134
|
+
waiting; doctor gains `ask-open` (info) and `ask-stale` (warning, 72 h); the gate
|
|
135
|
+
pass set has one spelling again, exported from `project.mjs` and imported by
|
|
136
|
+
`overnight.mjs` instead of hand-copied; `tiers` gains an advisory `conductor`
|
|
137
|
+
role with a `deep` floor, so the coordinator's model is named in the one file
|
|
138
|
+
where model names may live — and says on stderr that no plugin can change your
|
|
139
|
+
own session's model.
|
|
140
|
+
|
|
141
|
+
## 0.1.14 — 2026-08-14
|
|
142
|
+
|
|
143
|
+
### The repository remembers what went wrong — and eventually writes it into law
|
|
144
|
+
|
|
145
|
+
Tyran had three places a lesson could land and not one of them answered *how
|
|
146
|
+
often*. A journal `finding` dies with its initiative, correctly: it is that
|
|
147
|
+
run's discovery. A `.tyran/knowledge/` entry says what an agent must know
|
|
148
|
+
before touching a path. `CLAUDE.md` is law. Recurrence was counted nowhere, so
|
|
149
|
+
"this has burned us three times" was something a human had to remember, and on
|
|
150
|
+
the fourth time it was argued from scratch.
|
|
151
|
+
|
|
152
|
+
`MISTAKES.md` at your repository root is the store that was missing: what
|
|
153
|
+
happened, the root cause, the consequence, the prevention — newest first, plain
|
|
154
|
+
prose, yours to edit. The retrospective is its only writer, and it writes an
|
|
155
|
+
entry only for a breakage the initiative actually paid for. Every entry carries
|
|
156
|
+
a **signature**, and the signature is the whole point: the model decides
|
|
157
|
+
whether two failures are the *same* failure, and `scripts/mistakes.mjs`
|
|
158
|
+
(`add` · `repeats` · `promote`) does the counting.
|
|
159
|
+
|
|
160
|
+
**Three open entries under one signature** graduate the lesson into
|
|
161
|
+
`.tyran/knowledge/`, where every handoff touching those paths already delivers
|
|
162
|
+
it. **Five, still recurring after the knowledge entry shipped**, is evidence
|
|
163
|
+
the delivered rule was not enough — the strongest argument for law there is —
|
|
164
|
+
and at five `mistakes.mjs promote --law` **writes the rule into your
|
|
165
|
+
`CLAUDE.md`**. Not a proposal, not a queue: an autonomous write, between
|
|
166
|
+
`<!-- tyran:rules start -->` and `<!-- tyran:rules end -->` and never a byte
|
|
167
|
+
outside those markers. The line names the rule, its signature and the dated
|
|
168
|
+
entries that earned it; a `decision` event records the act; `--dry-run` prints
|
|
169
|
+
the line and writes nothing. You say no by deleting the line — the entries are
|
|
170
|
+
already at status `law`, so nothing puts it back. A fence that is absent is
|
|
171
|
+
appended once at the end, with its heading, and existing prose is never
|
|
172
|
+
reflowed; a fence that is malformed is refused by name, with nothing written.
|
|
173
|
+
|
|
174
|
+
The safety story is a boundary rather than a sentence. The shipped policy now
|
|
175
|
+
classes `CLAUDE.md` as **GATED**, which bans the hand and not the mechanism: a
|
|
176
|
+
subagent's free-hand `Write` is denied, while the script that demands five
|
|
177
|
+
recorded occurrences passes. Until this rule, the gate was silent on repo-root
|
|
178
|
+
files — its governed namespace is `.tyran/`, `.claude/` and the enforcement
|
|
179
|
+
scripts — so a subagent could rewrite the law it was bound by and nothing had
|
|
180
|
+
an opinion. An explicit rule outranks that namespace test, which is why one
|
|
181
|
+
line is enough. Seeding has always been create-only, so existing installs keep
|
|
182
|
+
their own policy untouched.
|
|
183
|
+
|
|
184
|
+
Seeding `MISTAKES.md` is create-only too, and **deleting the file is the whole
|
|
185
|
+
opt-out** — no knob for a file you can remove. `doctor --state` grew three
|
|
186
|
+
codes, 54 → **57**: `mistakes-repeat-unpromoted` (info — a lesson has earned
|
|
187
|
+
promotion), `mistakes-unreadable` (warning), and `claude-md-fence-missing`
|
|
188
|
+
(info — entries claim `law` but no fence exists to hold the rule). An absent
|
|
189
|
+
ledger is never a finding.
|
|
190
|
+
|
|
191
|
+
Stated rather than discovered: `MISTAKES.md` is **authored, not a byte-checked
|
|
192
|
+
projection**. A projection would report a hand edit as drift and destroy it on
|
|
193
|
+
the next render, and a human correcting a wrong root cause is the most valuable
|
|
194
|
+
edit this file will ever get. The cost is that nothing compares it to the
|
|
195
|
+
journal, so it can drift. Every entry cites its initiative and the event id
|
|
196
|
+
that proves it, which makes drift auditable by a human and **not** enforced by
|
|
197
|
+
a gate — a weaker guarantee than the projections carry, and both docs surfaces
|
|
198
|
+
say so instead of leaving you to assume parity.
|
|
199
|
+
|
|
200
|
+
This repository ships its own `MISTAKES.md`, five entries, one of them earned
|
|
201
|
+
during this release: the control-character write-guard refused an edit twice
|
|
202
|
+
because the editing tool turns `\uXXXX` escape text into the character itself,
|
|
203
|
+
so a regex class typed as escapes reached disk as raw C0 and bidi codepoints.
|
|
204
|
+
The guard was working; the author was the attacker.
|
|
205
|
+
|
|
206
|
+
### Keep the machine awake while the watcher waits
|
|
207
|
+
|
|
208
|
+
The overnight resume watcher's whole job is to be asleep for hours, which is
|
|
209
|
+
exactly the interval a laptop chooses to suspend in — and a suspended machine
|
|
210
|
+
takes the watcher and the network with it. `limits.keep_awake` (a real boolean,
|
|
211
|
+
default `false`) wraps the wait in a system-sleep inhibitor: `caffeinate -is`
|
|
212
|
+
on macOS, `systemd-inhibit --what=idle:sleep` on Linux. **Never `caffeinate
|
|
213
|
+
-d`**: that blocks the display sleep and with it the screen lock, and a machine
|
|
214
|
+
left running overnight that never locks is a security regression. The inhibitor
|
|
215
|
+
is released on every exit path including `SIGINT` and `SIGTERM`, an unsupported
|
|
216
|
+
platform degrades to a no-op instead of refusing to wait, and
|
|
217
|
+
`overnight.mjs schedule` tells you which way the knob is set — as a warning,
|
|
218
|
+
never a refusal.
|
|
219
|
+
|
|
220
|
+
### Measured
|
|
221
|
+
|
|
222
|
+
`node --test "tests/**/*.test.mjs"`: **1133 unit tests, 0 failures** — 34 of
|
|
223
|
+
them new in `tests/unit/mistakes.test.mjs` (the entry format, the counting
|
|
224
|
+
thresholds, the fence, and every refusal), 11 in `keepawake.test.mjs`.
|
|
225
|
+
`scan-control-chars`: clean over 185 tracked text files. The skill description
|
|
226
|
+
budget is unchanged at **4352 / 5000** — this release adds no skill and no
|
|
227
|
+
agent.
|
|
228
|
+
|
|
3
229
|
## 0.1.13 — 2026-08-13
|
|
4
230
|
|
|
5
231
|
### Six concurrent decisions, two ids
|
package/README.md
CHANGED
|
@@ -359,13 +359,14 @@ Published on npm as [`@jjanczur/tyran`](https://www.npmjs.com/package/@jjanczur/
|
|
|
359
359
|
command stays `tyran` either way; only the registry name is scoped, the same
|
|
360
360
|
pattern as `@angular/cli` giving you `ng`. `bin/tyran.mjs` exposes the same
|
|
361
361
|
scripts the plugin's hooks and skills already call — `doctor`, `scan-repo`,
|
|
362
|
-
`tiers`, `journal`, `schema`, `knowledge`, `board`, `overnight`, `statusline`, `stop-check`,
|
|
362
|
+
`tiers`, `journal`, `schema`, `knowledge`, `board`, `answer`, `overnight`, `statusline`, `stop-check`,
|
|
363
363
|
`scan-control-chars`, `desc-budget` — for a shell or a CI job with no Claude
|
|
364
364
|
Code session. Zero dependencies; `--help` lists them.
|
|
365
365
|
|
|
366
366
|
```bash
|
|
367
367
|
npx @jjanczur/tyran doctor --hooks # is any gate installed but unable to fire?
|
|
368
368
|
npx @jjanczur/tyran scan-repo --dir . # what this repo looks like, with provenance
|
|
369
|
+
npx @jjanczur/tyran answer render # the sheet of questions waiting on you
|
|
369
370
|
```
|
|
370
371
|
|
|
371
372
|
Exit codes propagate to the digit, so a CI step reddens exactly when the
|
|
@@ -443,6 +444,11 @@ underlying script does.
|
|
|
443
444
|
- [x] Read-only dashboard: the kanban board — `BOARD.md`/`board.json` next to
|
|
444
445
|
every journal, one cross-initiative `board.html` in the landing page's
|
|
445
446
|
own palette, refreshed on every subagent stop, plus `board.mjs --serve`
|
|
447
|
+
- [x] The mistakes ledger: `MISTAKES.md` at your repo root — what went wrong
|
|
448
|
+
here and how often — where three occurrences of one signature graduate a
|
|
449
|
+
lesson into `.tyran/knowledge/` and five write a rule into your
|
|
450
|
+
`CLAUDE.md`, inside Tyran's own fence — see
|
|
451
|
+
[docs/self-improvement.md](docs/self-improvement.md)
|
|
446
452
|
|
|
447
453
|
## Where this came from
|
|
448
454
|
|
package/agents/implementer.md
CHANGED
|
@@ -48,9 +48,21 @@ commits and anything written to disk are in English.**
|
|
|
48
48
|
the prediction written down first, and name the mechanism. A fix for a
|
|
49
49
|
failure you never reproduced cannot be shown to have worked.
|
|
50
50
|
- When the PR comes back with comments, follow `pr-feedback`.
|
|
51
|
-
3. **Decide technical questions yourself.**
|
|
52
|
-
|
|
53
|
-
|
|
51
|
+
3. **Decide technical questions yourself.** "Shall I continue?" is forbidden.
|
|
52
|
+
A product or visual decision, or one that would cross a boundary the handoff
|
|
53
|
+
named, is not yours to make — and it is also not a reason to sit still.
|
|
54
|
+
Raise it as an operator ask, in one command, against the MAIN checkout's
|
|
55
|
+
journal (the handoff carries its absolute path):
|
|
56
|
+
`node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs ask <abs-journal> <init>
|
|
57
|
+
--actor <you> --ticket <your ticket> --question '...' --recommendation '...'
|
|
58
|
+
--default '...'`. State both: what you would do, and what should ship if
|
|
59
|
+
nobody ever answers. Then **carry on under your own default** if the story
|
|
60
|
+
can proceed, or report and end if it cannot. The `Q-<n>` the command prints
|
|
61
|
+
goes in your report. Do **not** set `ticket.status` — the ask already moves
|
|
62
|
+
your ticket into the board's waiting-operator lane, and an override on top
|
|
63
|
+
of it hides the question. Ask the **conductor**, not the operator, for a
|
|
64
|
+
technical unblock: a lease, a corrected premise, a scope call inside the
|
|
65
|
+
handoff.
|
|
54
66
|
4. **Shared zones are append-only**, per the manifest. `git add` takes an
|
|
55
67
|
explicit list of paths — never `-A`, never `.`; they sweep in files
|
|
56
68
|
belonging to other windows, and that has already put blobs on a remote
|
package/agents/retro.md
CHANGED
|
@@ -21,6 +21,10 @@ to disk is in English.**
|
|
|
21
21
|
--ev finding`) — the claims agents recorded WITH proof, mid-run. Promote
|
|
22
22
|
the recurring ones into `.tyran/knowledge/` through the filter below; the
|
|
23
23
|
rest die with the initiative, which is correct.
|
|
24
|
+
Alongside them, `MISTAKES.md` at the repository root — the durable record of
|
|
25
|
+
what has gone WRONG here, newest first. You are its only writer: read it
|
|
26
|
+
before you decide anything, so a candidate that has already burned this repo
|
|
27
|
+
repeatedly is recognised as evidence rather than argued about again.
|
|
24
28
|
3. `git log` for the initiative: reverts, fixes of your own regressions,
|
|
25
29
|
repeated phases.
|
|
26
30
|
4. The current state of `skills/`, `agents/`, `scripts/` and the docs — **so
|
|
@@ -69,11 +73,22 @@ next retro relitigating the same idea.
|
|
|
69
73
|
report generators. A one-off harness from an initiative either becomes a
|
|
70
74
|
general tool or gets deleted; do not leave dead files behind.
|
|
71
75
|
- **Knowledge upkeep:** fold the reports' knowledge-brief verdicts into the
|
|
72
|
-
entries' counters (the fold procedure lives in `skills/retro/SKILL.md`,
|
|
73
|
-
|
|
76
|
+
entries' counters (the fold procedure lives in `skills/retro/SKILL.md`, under
|
|
77
|
+
"Write down what is true about THIS repo" — one home, not two), and retire or
|
|
78
|
+
split entries
|
|
74
79
|
`doctor --state` flags as `knowledge-entry-oversized`. An entry whose
|
|
75
80
|
counters say it stopped earning its keep is a deletion candidate, which
|
|
76
81
|
satisfies the deletion preference.
|
|
82
|
+
- **The mistakes ledger:** append an entry to `MISTAKES.md` for every breakage
|
|
83
|
+
this initiative actually paid for — what happened, the root cause, the
|
|
84
|
+
consequence, the prevention — and give it a **signature** you reuse for the
|
|
85
|
+
same failure rather than a near-synonym, because the signature is what makes
|
|
86
|
+
recurrence countable. Then promote what recurred: `mistakes.mjs repeats` says
|
|
87
|
+
which signatures crossed a graduation threshold and what each one has earned
|
|
88
|
+
— a `.tyran/knowledge/` entry, or a line you write into the `tyran:rules`
|
|
89
|
+
fence of the host `CLAUDE.md`. A discovery is not a mistake; if nothing
|
|
90
|
+
broke, write nothing. The procedure is the step of `skills/retro/SKILL.md`
|
|
91
|
+
that folds breakages into `MISTAKES.md` — one home, not two.
|
|
77
92
|
- **Documentation that pays forward:** the repo's detected configuration,
|
|
78
93
|
protocols, runbooks. **Every initiative should leave the repo better
|
|
79
94
|
described than it found it** — that is the part that makes each next
|
package/agents/reviewer.md
CHANGED
|
@@ -59,6 +59,13 @@ that keeps you.
|
|
|
59
59
|
review.
|
|
60
60
|
- When you find nothing, say so plainly. Manufacturing findings to look
|
|
61
61
|
thorough wastes a round and trains the conductor to discount you.
|
|
62
|
+
- A blocker that is really a **product or visual decision** is not a review
|
|
63
|
+
verdict. Raise it as an operator ask —
|
|
64
|
+
`node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs ask <abs-journal> <init>
|
|
65
|
+
--actor <you> --ticket <the ticket> --question '...' --recommendation
|
|
66
|
+
'...' --default '...'` — name the `Q-<n>` in your review, and give a
|
|
67
|
+
verdict on everything else. Holding a whole review open on one question
|
|
68
|
+
the operator has not seen is how a queue becomes a stall.
|
|
62
69
|
5. **Say what you did NOT check.** Platform you did not run on, concurrency
|
|
63
70
|
you did not exercise, the input class you skipped. This section is a merge
|
|
64
71
|
gate, not a courtesy: the conductor resolves every item as measured,
|
package/bin/tyran.mjs
CHANGED
|
@@ -72,6 +72,10 @@ export const COMMANDS = {
|
|
|
72
72
|
'knowledge.mjs',
|
|
73
73
|
'Select the knowledge entries that apply to a set of paths and print a paste-ready brief for a handoff.',
|
|
74
74
|
],
|
|
75
|
+
mistakes: [
|
|
76
|
+
'mistakes.mjs',
|
|
77
|
+
"Append to the repository's MISTAKES.md, count recurring signatures, and promote a recurring one into CLAUDE.md.",
|
|
78
|
+
],
|
|
75
79
|
overnight: [
|
|
76
80
|
'overnight.mjs',
|
|
77
81
|
'Schedule and run the usage-limit resume watcher: wait for the window reset, then resume the paused session.',
|
|
@@ -84,6 +88,10 @@ export const COMMANDS = {
|
|
|
84
88
|
'board.mjs',
|
|
85
89
|
'Render the cross-initiative kanban board — BOARD.md, board.json and the board.html dashboard — from the journals under .tyran/state/.',
|
|
86
90
|
],
|
|
91
|
+
answer: [
|
|
92
|
+
'answer.mjs',
|
|
93
|
+
'Write the sheet of questions waiting on you, then fold your answers back into the journal.',
|
|
94
|
+
],
|
|
87
95
|
'stop-check': [
|
|
88
96
|
'stop-check.mjs',
|
|
89
97
|
'Check the .tyran/STOP operator brake that halts a running initiative before its next spawn or merge.',
|