@jjanczur/tyran 0.1.19 → 0.1.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -11,7 +11,7 @@
11
11
  {
12
12
  "name": "tyran",
13
13
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
14
- "version": "0.1.19",
14
+ "version": "0.1.20",
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.19",
3
+ "version": "0.1.20",
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,80 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.20 — 2026-08-14
4
+
5
+ ### `.tyran/` was tracked, and an entire initiative inside it was not
6
+
7
+ `untrackedTyranDir` was all-or-nothing: one tracked file anywhere under
8
+ `.tyran/` and the whole directory reported healthy. Measured on a real install
9
+ whose `.tyran/` had been tracked for weeks — one initiative directory of six
10
+ files, its plan and the gate event recording two production database migrations
11
+ among them, had NEVER been committed, and a second was 33 events behind its
12
+ committed copy. Both passed. `journal.mjs append` writes the working tree and
13
+ nothing else, so an initiative nobody committed is one `git clean -fd` from
14
+ having never happened.
15
+
16
+ `doctor --state` now reads each initiative's ledger separately, in three states
17
+ rather than two:
18
+
19
+ - `initiative-untracked` (**warning**) — git has never seen it.
20
+ - `initiative-ignored` (**warning**) — a `.gitignore` rule covers it. Split out
21
+ because `git add` on an ignored path exits 0 and stages nothing, so the
22
+ untracked fix would have read as success while changing nothing.
23
+ - `initiative-uncommitted` (**info**, never fails the check) — tracked with
24
+ local changes, which is what an initiative in flight looks like ten seconds
25
+ after any append. It earns its keep at a merge boundary.
26
+
27
+ Two git invocations for the whole tree, not two per initiative: both listings
28
+ are read once and classified by path prefix in JS, so a repo with forty
29
+ initiatives costs the same three subprocesses as one with a single initiative
30
+ — and a test counts them, because that regression passes every behavioural
31
+ test there is. Under a wholly untracked `.tyran/` the directory-level finding
32
+ still reports alone rather than repeating itself once per initiative with
33
+ narrower advice each time.
34
+
35
+ ### Four things the conductor skill was letting agents rediscover
36
+
37
+ - **Interactive shell aliases hang an agent until the tool timeout.** An
38
+ agent's shell starts from the user's profile, so `alias cp='cp -i'` asks a
39
+ question nobody answers. The symptom is a timeout, which points at the
40
+ machine rather than at the alias, so it gets rediscovered every time: three
41
+ agents in one session, then again in a later one that had already read the
42
+ file it is now written in. STEP 0 probes for it.
43
+ - **A `Test timed out` measured under concurrency is not evidence.** The
44
+ hardware ceiling bounds agent count, not concurrent heavy phases. Re-run
45
+ serially and report the serial result. One overnight test failed exactly
46
+ that way inside the full suite while this release was being verified, and
47
+ passed alone.
48
+ - **An agent that dies on a terminal API error is resumed, not respawned** —
49
+ its context, its corrected premises and its uncommitted diff all survive.
50
+ - **Gitignored env files are absent from a fresh worktree too, and fail
51
+ quieter than dependencies**: 127 is loud, a skipped gated spec is not, so the
52
+ worktree reports a *cleaner* baseline than the repo has.
53
+
54
+ ### The README says what Tyran is, and the docs it links are the published ones
55
+
56
+ - **"What Tyran is" rewritten** to open on the failure a reader recognises — a
57
+ full context window, a plan somewhere in the scrollback, "the tests pass" as
58
+ a sentence rather than a result — before naming the mechanism that answers
59
+ it.
60
+ - **The named comparison is back on the front page.** Five rows of the eleven
61
+ in the FAQ, copied verbatim, plus a test that fails if a verdict moves in one
62
+ and not the other. The `Skills · agents it ships` row and the guard pinning
63
+ it were deleted rather than updated: the table under it and the sentence
64
+ under that already carry the same count, and three spellings of one answer is
65
+ the defect this repo calls ADR-21 — a test can hold one in place as easily as
66
+ prose can.
67
+ - **Every documentation link now points at the published site** rather than at
68
+ a markdown file: twenty in the README, three inside skills, and four in
69
+ `doctor`'s own fix lines — which reach repos that have no `docs/` directory
70
+ at all, where `see docs/journal.md` was a dead reference.
71
+ - **The Node version is stated once, where it applies.** It sat in the lede and
72
+ in the install section, neither of which runs Node: the scripts ship with the
73
+ plugin and Claude Code runs them. It now sits beside the one command that
74
+ needs it, `npx @jjanczur/tyran board`.
75
+ - **The dashboard GIF runs at 4 fps instead of 8.3** — the same recording, at a
76
+ speed a tab can actually be read at.
77
+
3
78
  ## 0.1.19 — 2026-08-14
4
79
 
5
80
  ### The board answered four questions on one scroll
package/README.md CHANGED
@@ -22,12 +22,24 @@
22
22
 
23
23
  ## What Tyran is
24
24
 
25
- Tyran is a Claude Code plugin that runs a task as a **team of agents instead of
26
- one long chat**. You describe the work; it interviews you briefly, plans, and
27
- drives fresh-context subagents through it. Execution state lives in an
28
- append-only journal committed to your repo rather than in the session window, so
29
- a restart, a compaction and a colleague on another branch read the same thing.
30
- Zero runtime dependencies, no build step, Node ≥ 22.
25
+ Every long Claude Code session ends the same way. The context fills up, the
26
+ plan is somewhere in the scrollback, and *"the tests pass"* is a sentence
27
+ rather than something you can check. Start a new session and you start
28
+ explaining from the beginning.
29
+
30
+ Tyran is a plugin that moves the work off the chat window. You describe a task;
31
+ it interviews you until the goal is unambiguous, sizes it, and drives
32
+ **fresh-context subagents** through it — a scout that only reads, an
33
+ implementer per story on its own branch, a reviewer holding no editing tools so
34
+ it cannot patch what it is grading. Every decision, spawn, report, merge and
35
+ open question is appended to a journal **committed to your repo**, and every
36
+ file you read afterwards is generated from that journal. A restart, a
37
+ compaction and a colleague on another branch all read the same thing.
38
+
39
+ Two rules are what make that worth the trouble. A report containing no raw
40
+ command output is **rejected by a hook**, not by good intentions. And every
41
+ write is classified against a policy file you own **before it happens**, so
42
+ *autonomous* is a setting with a blast radius rather than a promise.
31
43
 
32
44
  ![The Tyran dashboard, recorded live, moving through its four tabs: Overview with what is waiting on you and the strip of running agents each showing the time since it last signalled; Board, where selecting a ticket opens its initiative, agents and spend; Waiting on you, the open questions above the commands that answer them; and Spend, toggling the same split between tokens and cost](assets/board-demo.gif)
33
45
 
@@ -42,7 +54,7 @@ Zero runtime dependencies, no build step, Node ≥ 22.
42
54
  - **Reports that carry evidence, or are refused.** A `SubagentStop` hook
43
55
  rejects a report with no raw command output — measured on 55 real reports
44
56
  from this project's own agents: 53 pass, and both misses were not reports. It
45
- blocks silence, not forgery; [the evidence gate](docs/evidence-gate.md) is
57
+ blocks silence, not forgery; [the evidence gate](https://jjanczur.github.io/tyran/evidence-gate/) is
46
58
  precise about the difference.
47
59
  - **State you can read without a session.** The journal is the single source of
48
60
  truth; `STATE.md`, `PROGRESS.md`, `BOARD.md`, `board.json` and `board.html`
@@ -61,12 +73,12 @@ Zero runtime dependencies, no build step, Node ≥ 22.
61
73
  resume and stops — then a watcher wakes at the window reset and continues the
62
74
  same session. Leave it working and read the board in the morning. Both
63
75
  windows were hit live while the feature was being built; the protocol that
64
- survived them is what shipped. See [overnight mode](docs/overnight.md).
76
+ survived them is what shipped. See [overnight mode](https://jjanczur.github.io/tyran/overnight/).
65
77
 
66
- ## Tyran compared
78
+ ## Tyran vs. an ordinary session
67
79
 
68
- The axis, not the winner. These rows compare against an ordinary agent session
69
- — a comparison that can be made without guessing at another tool's internals.
80
+ The axis, not the winner — a comparison that can be made without guessing at
81
+ anyone's internals.
70
82
 
71
83
  | | An ordinary agent session | Tyran |
72
84
  |---|---|---|
@@ -75,15 +87,33 @@ The axis, not the winner. These rows compare against an ordinary agent session
75
87
  | Which model does which job | one model for the whole session | four tiers resolved from `.tyran/config.yaml`, per role, with a floor under the judgements everything downstream trusts |
76
88
  | What happens after the work | nothing | a retrospective writes what this repo taught it back into this repo |
77
89
  | What it adds to your install | — | zero runtime dependencies, no build step |
78
- | Skills · agents it ships | — | 14 · 4 |
90
+
91
+ ## Tyran vs. other Claude Code orchestrators
92
+
93
+ Five rows of eleven, verified against those projects' **code and public issue
94
+ trackers** (July 2026) rather than their READMEs. ✅ shipped and enforced ·
95
+ ⚠️ partial or prompt-only · ❌ absent or broken · 🎯 committed in the design,
96
+ ships test-gated.
97
+
98
+ | Capability | **Tyran** | oh-my-claudecode | metaswarm | pilotfish | pro-workflow |
99
+ |---|:---:|:---:|:---:|:---:|:---:|
100
+ | Evidence contract that **blocks**: no raw command output → report rejected | ✅ | ⚠️ advisory¹ | ⚠️ prompt | ⚠️ prompt | ❌ |
101
+ | Execution state survives restart & compaction (journal + re-inject) | ✅ | ⚠️ | ❌² | ❌ | ⚠️ |
102
+ | Plugin update **never** destroys local learning (3 layers + delta agent) | 🎯 | ❌³ | — | — | ⚠️ |
103
+ | Secret gate on commit/push with verified scan coverage, no `--no-verify` escape | ✅ | ❌ | ❌ | ❌ | ⚠️ |
104
+ | Clean install: 2 commands, **never writes into your `~/.claude`** | ✅ | ❌³ | ⚠️ | ❌ | ⚠️ |
105
+
106
+ ¹ Their deliverable check is explicitly non-blocking. ² Their issues
107
+ #32/#33/#36: a crash loses loop state. ³ Open issues #3535/#3536: an update
108
+ deletes user files from `~/.claude`. The other six rows — repo-specific
109
+ learning, cost tiers, independent review, context budget, safe parallelism, OSS
110
+ hygiene — and every footnote in full are in
111
+ [the FAQ](https://jjanczur.github.io/tyran/faq/#how-tyran-compares-to-other-claude-code-orchestrators).
79
112
 
80
113
  Worth knowing before tuning anything: cache reads were measured at roughly
81
114
  three quarters of a real session's cost, and the conductor's own context at
82
115
  between 44% and 86% of a tree's tokens — so the lever is context size and turn
83
- count, not the price of a model. A cell-by-cell comparison against four other
84
- Claude Code orchestrators, verified against their code and public issue
85
- trackers, is in
86
- [the FAQ](docs/faq.md#how-tyran-compares-to-other-claude-code-orchestrators).
116
+ count, not the price of a model.
87
117
 
88
118
  ## Install
89
119
 
@@ -97,11 +127,13 @@ Inside Claude Code:
97
127
 
98
128
  Restart Claude Code afterwards — hooks and agents are read when a session
99
129
  starts, so an install you have not restarted into is an install you are not
100
- running. `/tyran:hello` is the smoke test. Requirements: Claude Code ≥ 2.1;
101
- Tyran's scripts are plain Node ≥ 22 and ship with the plugin, so you never run
102
- npm. `/plugin` is a slash command a human has to type — the prompt that has
103
- Claude Code install itself, the npm package for a shell or a CI job, updating
104
- and uninstalling are all in [getting started](docs/getting-started.md).
130
+ running. `/tyran:hello` is the smoke test. The only requirement is **Claude
131
+ Code ≥ 2.1**: the scripts ship with the plugin and Claude Code runs them, so
132
+ there is nothing to install and no version of anything else to match.
133
+ `/plugin` is a slash command a human has to type — the prompt that has Claude
134
+ Code install itself, the npm package for a shell or a CI job, updating and
135
+ uninstalling are all in
136
+ [getting started](https://jjanczur.github.io/tyran/getting-started/).
105
137
 
106
138
  ## Use it
107
139
 
@@ -130,8 +162,10 @@ echo "wrong branch — hold everything" > .tyran/STOP
130
162
  npx @jjanczur/tyran board --dir .tyran --serve
131
163
  ```
132
164
 
133
- A read-only board on loopback, re-rendered on every request. Four tabs, because
134
- the page answers four questions:
165
+ A read-only board on loopback, re-rendered on every request. That command is
166
+ the one place a Node version matters — `npx` runs the scripts outside Claude
167
+ Code, and they need **Node ≥ 22**. Four tabs, because the page answers four
168
+ questions:
135
169
 
136
170
  - **Overview** — what is waiting on you, agents running, progress, tickets that
137
171
  need a human; then the agent strip, each chip carrying the time since that
@@ -147,7 +181,7 @@ the page answers four questions:
147
181
 
148
182
  The same page is written to `.tyran/state/board.html` and refreshed after every
149
183
  agent, so you can also just open the file. Spend is served rather than embedded
150
- and absent over `file://` — [the board](docs/board.md) says why.
184
+ and absent over `file://` — [the board](https://jjanczur.github.io/tyran/board/) says why.
151
185
 
152
186
  ## What ships
153
187
 
@@ -157,29 +191,31 @@ repo, initiative or not — and the other eight are standalone protocols.
157
191
 
158
192
  | Skill | What it does |
159
193
  |---|---|
160
- | [`run`](skills/run/SKILL.md) | the conductor — interviews, sizes, plans, delegates, merges |
161
- | [`setup`](skills/setup/SKILL.md) | reads the repo and writes `.tyran/config.yaml`, provenance per value |
162
- | [`status`](skills/status/SKILL.md) | where an initiative got to, from the journal rather than from memory |
163
- | [`doctor`](skills/doctor/SKILL.md) | is any gate installed but unable to fire; is the state self-consistent |
164
- | [`retro`](skills/retro/SKILL.md) | the anti-bloat curator that changes Tyran, never your product code |
165
- | [`hello`](skills/hello/SKILL.md) | proves the plugin is installed and its paths resolve |
166
- | [`code-review`](skills/code-review/SKILL.md) | the dimensions a diff is read against, and the rule that you refute a finding before reporting it |
167
- | [`root-cause`](skills/root-cause/SKILL.md) | reproduce first, one variable per experiment, exit by naming the mechanism |
168
- | [`browser-check`](skills/browser-check/SKILL.md) | a UI pass that returns counts — console errors, failed responses, computed styles |
169
- | [`deslop`](skills/deslop/SKILL.md) | the optimization pass: delete before you add, behaviour pinned by a test that ran first |
170
- | [`pr-feedback`](skills/pr-feedback/SKILL.md) | all three of GitHub's comment surfaces, a disposition for every comment |
171
- | [`fidelity-gate`](skills/fidelity-gate/SKILL.md) | build 1:1 against a frozen mockup, measured rather than eyeballed |
172
- | [`prompt-tuning`](skills/prompt-tuning/SKILL.md) | tune a non-deterministic output without chasing noise — noise baseline first |
173
- | [`skill-writing`](skills/skill-writing/SKILL.md) | what a skill has to earn before it ships, and the test that proves it fires |
194
+ | `run` | the conductor — interviews, sizes, plans, delegates, merges |
195
+ | `setup` | reads the repo and writes `.tyran/config.yaml`, provenance per value |
196
+ | `status` | where an initiative got to, from the journal rather than from memory |
197
+ | `doctor` | is any gate installed but unable to fire; is the state self-consistent |
198
+ | `retro` | the anti-bloat curator that changes Tyran, never your product code |
199
+ | `hello` | proves the plugin is installed and its paths resolve |
200
+ | `code-review` | the dimensions a diff is read against, and the rule that you refute a finding before reporting it |
201
+ | `root-cause` | reproduce first, one variable per experiment, exit by naming the mechanism |
202
+ | `browser-check` | a UI pass that returns counts — console errors, failed responses, computed styles |
203
+ | `deslop` | the optimization pass: delete before you add, behaviour pinned by a test that ran first |
204
+ | `pr-feedback` | all three of GitHub's comment surfaces, a disposition for every comment |
205
+ | `fidelity-gate` | build 1:1 against a frozen mockup, measured rather than eyeballed |
206
+ | `prompt-tuning` | tune a non-deterministic output without chasing noise — noise baseline first |
207
+ | `skill-writing` | what a skill has to earn before it ships, and the test that proves it fires |
174
208
 
175
209
  Agents: `tyran:scout` (recon, read-only), `tyran:implementer` (one story, own
176
210
  branch), `tyran:reviewer` (no editing tools — it cannot patch what it is
177
211
  grading), `tyran:retro`. A skill is admitted only when something already asks
178
212
  for the protocol by name, and every description is loaded into every session
179
213
  whether the skill fires or not — so the combined length is capped and CI
180
- enforces the cap (4352 of 5000 characters). What each one assumes, and who
181
- invokes it, is in [skills and agents](docs/skills.md). Behind all of it: 1289
182
- unit tests, run with `node --test "tests/**/*.test.mjs"`.
214
+ enforces the cap (4352 of 5000 characters). What each one assumes, when it
215
+ fires and who invokes it, is in
216
+ [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
217
+ themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
218
+ it: 1297 unit tests, run with `node --test "tests/**/*.test.mjs"`.
183
219
 
184
220
  ## Documentation
185
221
 
@@ -188,16 +224,16 @@ Everything below also reads as a site, with search and rendered diagrams:
188
224
 
189
225
  | | |
190
226
  |---|---|
191
- | [Getting started](docs/getting-started.md) | install, first run, the command line, updating |
192
- | [Architecture](docs/architecture.md) | the four failures, the three layers, the hooks, the principles, the roadmap |
193
- | [Skills and agents](docs/skills.md) · [the roster](docs/agents.md) | what each one assumes and who invokes it; the tier and effort table, the `.tyran/STOP` brake |
194
- | [Configuration](docs/configuration.md) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes |
195
- | [Self-improvement](docs/self-improvement.md) | how Tyran learns your repo, and its guardrails |
196
- | [Journal](docs/journal.md) · [projections](docs/projections.md) | the append-only event schema, and what is generated from it |
197
- | [The board](docs/board.md) · [the spend ledger](docs/cost.md) | lanes, answering a question, and what a run cost |
198
- | [Overnight mode](docs/overnight.md) · [doctor](docs/doctor.md) | usage-limit pause and scheduled resume; the `--state` and `--hooks` checks |
199
- | [Hook runtime](docs/hooks.md) · [evidence gate](docs/evidence-gate.md) · [policy gate](docs/policy-gate.md) | gates versus probes and why hooks fail open; the criterion and its limits; path classes and where each stops |
200
- | [FAQ](docs/faq.md) | short answers, the comparison table, and where this came from |
227
+ | [Getting started](https://jjanczur.github.io/tyran/getting-started/) | install, first run, the command line, updating |
228
+ | [Architecture](https://jjanczur.github.io/tyran/architecture/) | the four failures, the three layers, the hooks, the principles, the roadmap |
229
+ | [Skills and agents](https://jjanczur.github.io/tyran/skills/) · [the roster](https://jjanczur.github.io/tyran/agents/) | what each one assumes and who invokes it; the tier and effort table, the `.tyran/STOP` brake |
230
+ | [Configuration](https://jjanczur.github.io/tyran/configuration/) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes |
231
+ | [Self-improvement](https://jjanczur.github.io/tyran/self-improvement/) | how Tyran learns your repo, and its guardrails |
232
+ | [Journal](https://jjanczur.github.io/tyran/journal/) · [projections](https://jjanczur.github.io/tyran/projections/) | the append-only event schema, and what is generated from it |
233
+ | [The board](https://jjanczur.github.io/tyran/board/) · [the spend ledger](https://jjanczur.github.io/tyran/cost/) | lanes, answering a question, and what a run cost |
234
+ | [Overnight mode](https://jjanczur.github.io/tyran/overnight/) · [doctor](https://jjanczur.github.io/tyran/doctor/) | usage-limit pause and scheduled resume; the `--state` and `--hooks` checks |
235
+ | [Hook runtime](https://jjanczur.github.io/tyran/hooks/) · [evidence gate](https://jjanczur.github.io/tyran/evidence-gate/) · [policy gate](https://jjanczur.github.io/tyran/policy-gate/) | gates versus probes and why hooks fail open; the criterion and its limits; path classes and where each stops |
236
+ | [FAQ](https://jjanczur.github.io/tyran/faq/) | short answers, the comparison table, and where this came from |
201
237
  | [Contributing](CONTRIBUTING.md) | the dev loop, the test commands, the enforced rules |
202
238
 
203
239
  ## License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.19",
3
+ "version": "0.1.20",
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": {
@@ -206,6 +206,12 @@ export const SEVERITY_BY_CODE = Object.freeze(
206
206
  'state-stray-file': 'warning',
207
207
  'state-legacy-initiatives-dir': 'warning',
208
208
  'lease-file-tracked': 'warning',
209
+ // the ledger in git. `uncommitted` is INFO on purpose: every append
210
+ // produces that state within seconds, and a warning that is on during
211
+ // normal operation is a warning people learn to scroll past.
212
+ 'initiative-untracked': 'warning',
213
+ 'initiative-ignored': 'warning',
214
+ 'initiative-uncommitted': 'info',
209
215
  // the mistakes ledger. `mistakes-unreadable` is a WARNING, not the `error`
210
216
  // that `knowledge-unreadable` and `config-unreadable` carry: nothing
211
217
  // mechanical consumes MISTAKES.md at write time, so an unreadable one
@@ -1162,6 +1168,98 @@ export function untrackedTyranDir(repoRoot, run, tyranDirName = '.tyran') {
1162
1168
  return run(['ls-files', '--', tyranDirName]).trim() === '';
1163
1169
  }
1164
1170
 
1171
+ /**
1172
+ * Which initiative ledgers git has never seen, and which carry local changes.
1173
+ *
1174
+ * `untrackedTyranDir` above is all-or-nothing: one tracked file anywhere under
1175
+ * `.tyran/` and the whole directory reports healthy. That is the wrong
1176
+ * granularity for what iron rule 1 actually asks for. Measured on a real
1177
+ * install whose `.tyran/` had been tracked for weeks: one initiative directory
1178
+ * of six files — its plan, and the gate event recording two production
1179
+ * database migrations — had NEVER been committed, and a second was 33 events
1180
+ * behind its committed copy. The directory-level check passed on both.
1181
+ * `journal.mjs append` writes the working tree and nothing else, so an
1182
+ * initiative nobody committed is one `git clean -fd` from having never
1183
+ * happened.
1184
+ *
1185
+ * Three states, because the same loss needs three different sentences:
1186
+ *
1187
+ * - `untracked` — git has never seen this ledger. Wrong at any moment.
1188
+ * - `ignored` — a rule in some `.gitignore` covers it. The same loss, but
1189
+ * `git add` on a path git is ignoring is a SILENT no-op, so the advice the
1190
+ * untracked case gives would look like it worked and change nothing.
1191
+ * - `uncommitted` — tracked, with local changes. What an initiative in
1192
+ * flight looks like ten seconds after any append, so it is worth saying
1193
+ * only at a merge boundary, and never worth failing a check over.
1194
+ *
1195
+ * Two git invocations for the whole tree rather than two per initiative: the
1196
+ * listings are read once and classified by path prefix in JS. A repo can hold
1197
+ * dozens of initiatives and this runs behind the SessionStart deadline. The
1198
+ * prefix is built in git's own output convention (repo-relative, forward
1199
+ * slashes) for the same reason `trackedLeaseFiles` filters in JS instead of
1200
+ * trusting pathspec globbing.
1201
+ *
1202
+ * No second `rev-parse`: the caller reaches this only when `untrackedTyranDir`
1203
+ * returned a boolean rather than null, which is already the answer to whether
1204
+ * git can answer.
1205
+ */
1206
+ export function initiativeGitStates(run, tyranDirName, names) {
1207
+ const lines = (out) => out.split('\n').filter((line) => line !== '');
1208
+ const tracked = lines(run(['ls-files', '--', tyranDirName]));
1209
+ // `--ignored` costs nothing on a call being made anyway and is the whole
1210
+ // difference between "you forgot" and "a rule you wrote is hiding it".
1211
+ // Porcelain v1 is `XY<space>path`; git collapses a wholly untracked or
1212
+ // ignored DIRECTORY into a single entry, so a recorded path can be shorter
1213
+ // than the prefix as well as longer — hence the check in both directions.
1214
+ const status = lines(run(['status', '--porcelain', '--ignored', '--', tyranDirName]));
1215
+ const paths = (keep) => status.filter((l) => l.startsWith('!! ') === keep).map((l) => l.slice(3));
1216
+ const ignored = paths(true);
1217
+ const dirty = paths(false);
1218
+ const covers = (entries, prefix) =>
1219
+ entries.some((path) => path.startsWith(prefix) || prefix.startsWith(path));
1220
+ const states = new Map();
1221
+ for (const name of names) {
1222
+ const prefix = `${tyranDirName}/state/${name}/`;
1223
+ if (tracked.some((path) => path.startsWith(prefix))) {
1224
+ states.set(name, covers(dirty, prefix) ? 'uncommitted' : 'committed');
1225
+ } else {
1226
+ states.set(name, covers(ignored, prefix) ? 'ignored' : 'untracked');
1227
+ }
1228
+ }
1229
+ return states;
1230
+ }
1231
+
1232
+ /** The finding for one non-`committed` ledger state, or null for `committed`. */
1233
+ function ledgerFinding(state, path, name, gitPath) {
1234
+ if (state === 'untracked') {
1235
+ return finding(
1236
+ 'initiative-untracked',
1237
+ show(path),
1238
+ 'git has never seen this ledger — `journal.mjs append` writes the working tree and nothing ' +
1239
+ 'else, so an initiative nobody committed is one `git clean -fd` from having never happened, ' +
1240
+ 'and a worktree carries tracked files only, so the agents working in one never read it',
1241
+ `git add ${sq(gitPath)} && git commit -m ${sq(`chore(tyran): record the ${name} ledger`)}`,
1242
+ );
1243
+ }
1244
+ if (state === 'ignored') {
1245
+ return finding(
1246
+ 'initiative-ignored',
1247
+ show(path),
1248
+ 'a .gitignore rule covers this ledger, so nothing under it can be committed — the journal is ' +
1249
+ 'the copy that is supposed to outlive the session, and this one exists on one machine only',
1250
+ `git check-ignore -v ${sq(`${gitPath}/journal.jsonl`)} # the rule doing it; ` +
1251
+ '`git add` alone is a silent no-op on an ignored path',
1252
+ );
1253
+ }
1254
+ return finding(
1255
+ 'initiative-uncommitted',
1256
+ show(path),
1257
+ 'the ledger has uncommitted changes — ordinary mid-initiative, a gap at a merge boundary: ' +
1258
+ 'rule 1 asks for the ledger to travel with the work, not to be committed once at the end',
1259
+ `git add ${sq(gitPath)} && git commit -m ${sq(`chore(tyran): ${name} ledger`)}`,
1260
+ );
1261
+ }
1262
+
1165
1263
  /**
1166
1264
  * Lease files committed to git. A lease records who holds a worktree or a
1167
1265
  * heavy slot RIGHT NOW; committing one makes every parallel merge conflict on
@@ -1258,7 +1356,7 @@ export function mistakesFindings(repoRoot) {
1258
1356
  show(claudePath),
1259
1357
  `${lawEntries} entr${lawEntries === 1 ? 'y' : 'ies'} in ${MISTAKES_FILE} ` +
1260
1358
  `claim${lawEntries === 1 ? 's' : ''} status \`law\`, and ${why}`,
1261
- `node scripts/mistakes.mjs repeats --file ${sq(path)} # see docs/self-improvement.md for the fence`,
1359
+ `node scripts/mistakes.mjs repeats --file ${sq(path)} # see https://jjanczur.github.io/tyran/self-improvement/ for the fence`,
1262
1360
  ),
1263
1361
  );
1264
1362
  }
@@ -1371,7 +1469,7 @@ export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
1371
1469
  show(sidecarPath),
1372
1470
  `limits.mode is "${show(limits.mode)}" but the usage telemetry sidecar is ${sidecar === null ? 'absent' : 'over a day old'} — ` +
1373
1471
  'the gate fails open without it, so the configured pause protects nothing. The statusline ' +
1374
- 'helper is operator-installed; see docs/overnight.md',
1472
+ 'helper is operator-installed; see https://jjanczur.github.io/tyran/overnight/',
1375
1473
  `node scripts/statusline.mjs --sidecar-only # wired into the user-settings statusLine command`,
1376
1474
  ),
1377
1475
  );
@@ -1506,6 +1604,18 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1506
1604
  finding('state-unreadable', show(stateDir), `cannot list state/ (${errText(err)})`),
1507
1605
  );
1508
1606
  }
1607
+ // Only when `.tyran/` as a whole IS tracked. Under a wholly untracked
1608
+ // directory every initiative would repeat the finding above, each time
1609
+ // with narrower advice than the one that already covers it, and a check
1610
+ // that says the same thing N+1 times is a check people learn to skip.
1611
+ const gitStates =
1612
+ untracked === false
1613
+ ? initiativeGitStates(
1614
+ gitRun,
1615
+ basename(root),
1616
+ sortedNames(names).filter((name) => isDirectory(join(stateDir, name))),
1617
+ )
1618
+ : null;
1509
1619
  for (const name of sortedNames(names)) {
1510
1620
  const path = join(stateDir, name);
1511
1621
  if (!isDirectory(path)) {
@@ -1526,6 +1636,10 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1526
1636
  }
1527
1637
  const result = checkInitiative(stateDir, name, { now, staleHours });
1528
1638
  findings.push(...result.findings);
1639
+ const ledger = gitStates?.get(name) ?? 'committed';
1640
+ if (ledger !== 'committed') {
1641
+ findings.push(ledgerFinding(ledger, path, name, `${basename(root)}/state/${name}`));
1642
+ }
1529
1643
  initiatives.push(`${show(name)} (${result.events} event(s))`);
1530
1644
  }
1531
1645
  }
@@ -1542,7 +1656,7 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1542
1656
  'legacy layout — initiative files (PLAN.md, NOTES.md, RETRO.md, locks/) live under ' +
1543
1657
  'state/<initiative>/ since 0.1.9. Mechanical consumers read only state/, so anything ' +
1544
1658
  'kept here is invisible to the projections, the retrospective and the session summary',
1545
- `ls -la ${sq(legacyDir)} # relocate the contents by hand, one initiative directory at a time, into ${sq(join(dir, 'state'))} — see docs/journal.md`,
1659
+ `ls -la ${sq(legacyDir)} # relocate the contents by hand, one initiative directory at a time, into ${sq(join(dir, 'state'))} — see https://jjanczur.github.io/tyran/journal/`,
1546
1660
  ),
1547
1661
  );
1548
1662
  }
@@ -1564,7 +1678,7 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1564
1678
  `${trackedLeases.length} lease file(s) committed to git — a lease records who holds a resource ` +
1565
1679
  'RIGHT NOW, so a committed one conflicts on every parallel merge and resurrects as a phantom ' +
1566
1680
  'holder on every checkout',
1567
- `git ls-files -- ${sq(basename(root))} # list them; keep 'state/*/locks/' in .tyran/.gitignore and un-track the files by hand — see docs/configuration.md`,
1681
+ `git ls-files -- ${sq(basename(root))} # list them; keep 'state/*/locks/' in .tyran/.gitignore and un-track the files by hand — see https://jjanczur.github.io/tyran/configuration/`,
1568
1682
  ),
1569
1683
  );
1570
1684
  }
@@ -101,7 +101,7 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/mistakes.mjs" repeats
101
101
  It prints one line per signature that has crossed a graduation threshold,
102
102
  ending in what that signature has earned. Act on that recommendation — the
103
103
  thresholds themselves, and why they are where they are, live in
104
- `docs/self-improvement.md`.
104
+ https://jjanczur.github.io/tyran/self-improvement/.
105
105
 
106
106
  - **`promote to .tyran/knowledge/`** — write the rule into
107
107
  `.tyran/knowledge/<topic>.yaml`, scoped with `applies_to` so it reaches only
@@ -70,6 +70,13 @@ English regardless.
70
70
  server start vanish on restart, so restarts stop being deterministic;
71
71
  - probe the toolchain with `command -v` for every tool the plan names, and
72
72
  confirm your own file-writing path works before you rely on it;
73
+ - **probe for interactive aliases** — `alias cp mv rm 2>/dev/null` — because
74
+ an agent's shell is started from the user's profile, so `alias cp='cp -i'`
75
+ turns a copy into a question with nobody to answer it and the call burns
76
+ its whole timeout. Put `command cp` in the handoff when one is set. The
77
+ symptom is a timeout, which points at the machine rather than the alias,
78
+ so it is rediscovered every time: measured three times in one session, in
79
+ three different agents, and again in a later one that had read this file;
73
80
  - **dry-run every automaton** for one no-op iteration before you trust it
74
81
  with unattended work. Trust dialogs and missing dependencies surface
75
82
  then, not at 3am.
@@ -227,6 +234,15 @@ open one.
227
234
  carries an explicit **"NO INDEPENDENT REVIEW"** stamp; staying quiet about
228
235
  it is forbidden. Tests for every non-trivial change. Repo validation per
229
236
  the project configuration. You merge, sequentially.
237
+ - **A `Test timed out` measured while another heavy phase was running is
238
+ not evidence of a defect.** Re-run it serially, report the serial result,
239
+ and say the first run was concurrent. The hardware ceiling bounds AGENT
240
+ count, not concurrent heavy phases, so an agent can respect it and still
241
+ produce a red only the machine caused — five such failures in one session,
242
+ all green on a serial re-run.
243
+ - **An agent that dies on a terminal API error is RESUMED, not respawned.**
244
+ Its context, its corrected premises and its uncommitted diff all survive
245
+ the death; a fresh agent on the same handoff redoes work already on disk.
230
246
  - **How a diff is read is the `code-review` skill**; what the verdict looks
231
247
  like stays in `tyran:reviewer`. The part you enforce as conductor is that
232
248
  a finding arrives as an input and an expected result — anything vaguer
@@ -345,6 +361,11 @@ open one.
345
361
  manifest and lockfile are already a SHARED ZONE nobody may edit, so the
346
362
  dependencies are guaranteed identical, and a per-worktree install is how
347
363
  a lockfile drifts. Say in the handoff which directory you linked.
364
+ **Gitignored environment files are missing for the same reason, and they
365
+ fail QUIETER**: a missing dependency exits 127, a missing `.env` makes the
366
+ gated specs SKIP — so the worktree reports a *cleaner* baseline than the
367
+ repo has and the difference reads as good news. Link those too, and name
368
+ them in the handoff.
348
369
  - **`.tyran/state/**` lives in the main checkout only.** An agent told to
349
370
  append to `NOTES.md` from inside a worktree must use the absolute
350
371
  main-repo path, or it writes into a copy nobody reads.
@@ -437,6 +458,6 @@ open one.
437
458
  stop. Never route around the allowlist: the point of pausing at 97% is
438
459
  that the last 3% pays for a clean checkpoint instead of a corpse. The
439
460
  scheduler resumes the session after the reset (or notifies and holds on a
440
- long, weekly-shaped wait — `docs/overnight.md`); a resumed session starts
461
+ long, weekly-shaped wait — https://jjanczur.github.io/tyran/overnight/); a resumed session starts
441
462
  from the `usage-limit-pause` checkpoint and first closes the open
442
463
  usage-limit gate with `result: passed`.
@@ -164,7 +164,7 @@ copies of the config. Stage explicit paths until this commit exists.
164
164
 
165
165
  ## 7. Offer overnight mode — and say plainly what the operator must do
166
166
 
167
- Overnight mode (`docs/overnight.md`) pauses autonomous work near the
167
+ Overnight mode (https://jjanczur.github.io/tyran/overnight/) pauses autonomous work near the
168
168
  subscription usage limit and resumes after the window resets. It is OFF by
169
169
  default because its telemetry is a statusline the plugin cannot install:
170
170
  `.claude/settings.json` in user scope is the operator's file, and the policy
@@ -11,7 +11,7 @@
11
11
  #
12
12
  # Validate after editing: node scripts/schema.mjs validate config .tyran/config.yaml
13
13
 
14
- # Cost mode: eco | balanced | full (see docs/configuration.md)
14
+ # Cost mode: eco | balanced | full (see https://jjanczur.github.io/tyran/configuration/)
15
15
  profile: balanced
16
16
 
17
17
  # Deployment autonomy: P1 branch-only · P2 staging · P3 merge to main.
@@ -44,7 +44,7 @@ validation:
44
44
  shared_zones: []
45
45
 
46
46
  # Overnight mode — pause autonomous work near the subscription usage limits
47
- # and resume after the window resets (docs/overnight.md). Requires the
47
+ # and resume after the window resets (https://jjanczur.github.io/tyran/overnight/). Requires the
48
48
  # operator-installed statusline helper (scripts/statusline.mjs), which is the
49
49
  # only place the platform exposes usage telemetry; without it the gate is
50
50
  # silent and doctor says so.