@jjanczur/tyran 0.1.13 → 0.1.15

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.13",
14
+ "version": "0.1.15",
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.13",
3
+ "version": "0.1.15",
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,140 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.15 — 2026-08-14
4
+
5
+ ### Fifteen questions, ten minutes, and the swarm moves
6
+
7
+ An agent that hits a product decision no longer stops and waits for you. It
8
+ raises the question — `journal.mjs ask`, one command, which mints the id under
9
+ the journal's write lock so two agents asking at the same moment get two
10
+ questions rather than one — states what it recommends and what should ship if
11
+ nobody ever answers, and takes the next ticket. The question is a `gate` whose
12
+ `kind` IS its id, `Q-<n>`: the closed event set stays at 17, the board's
13
+ waiting-on-you queue already rendered it, and `answered` was already a pass
14
+ result. What was missing was an identity and a way in.
15
+
16
+ The way in is a text file. `tyran answer render` writes `.tyran/state/ANSWERS.md`
17
+ — every open question across every initiative, the ones with no recorded default
18
+ first, because those are the only ones where saying nothing has no safe outcome.
19
+ You type under `answer:`. **Blank accepts the recorded default**, verbatim, and
20
+ still records it as a decision; `-` leaves it for next time; anything else is your
21
+ answer in your own words. `tyran answer apply` folds them back as `decision` +
22
+ `gate result: answered` pairs — decision first, so a crash leaves a visible orphan
23
+ decision rather than a closed question whose answer was never written down — then
24
+ re-renders every projection and the board. It reads the question, the default and
25
+ the ticket back out of the journal, never out of the sheet, and it is
26
+ all-or-nothing: one unparseable block and nothing at all is appended, with the
27
+ line number.
28
+
29
+ Answering a question no longer needs the conductor to be awake. `SessionStart`
30
+ records the session id in `.tyran/state/conductor.json`, so `apply --resume` can
31
+ put the swarm back on it — and refuses while that session is still alive, because
32
+ two conductors on one journal is a hazard this repo has already paid for once.
33
+
34
+ One correction found while building it. Parking an asked ticket **hid** it: the
35
+ board checks a `ticket.status` override before the ask, so our own demo fixture
36
+ showed `waiting-operator (0)` with a question open — the fixture is corrected and
37
+ the skill now forbids the override.
38
+
39
+ Also: `question`, `recommendation`, `default` and `answer` are capped at 2000
40
+ codepoints (rejected, never truncated — historical oversizes stay warnings);
41
+ `STATE.md`'s open-gates table and the SessionStart probe now carry the question
42
+ text, so a resumed conductor sees *what* it asked and not merely that it is
43
+ waiting; doctor gains `ask-open` (info) and `ask-stale` (warning, 72 h); the gate
44
+ pass set has one spelling again, exported from `project.mjs` and imported by
45
+ `overnight.mjs` instead of hand-copied; `tiers` gains an advisory `conductor`
46
+ role with a `deep` floor, so the coordinator's model is named in the one file
47
+ where model names may live — and says on stderr that no plugin can change your
48
+ own session's model.
49
+
50
+ ## 0.1.14 — 2026-08-14
51
+
52
+ ### The repository remembers what went wrong — and eventually writes it into law
53
+
54
+ Tyran had three places a lesson could land and not one of them answered *how
55
+ often*. A journal `finding` dies with its initiative, correctly: it is that
56
+ run's discovery. A `.tyran/knowledge/` entry says what an agent must know
57
+ before touching a path. `CLAUDE.md` is law. Recurrence was counted nowhere, so
58
+ "this has burned us three times" was something a human had to remember, and on
59
+ the fourth time it was argued from scratch.
60
+
61
+ `MISTAKES.md` at your repository root is the store that was missing: what
62
+ happened, the root cause, the consequence, the prevention — newest first, plain
63
+ prose, yours to edit. The retrospective is its only writer, and it writes an
64
+ entry only for a breakage the initiative actually paid for. Every entry carries
65
+ a **signature**, and the signature is the whole point: the model decides
66
+ whether two failures are the *same* failure, and `scripts/mistakes.mjs`
67
+ (`add` · `repeats` · `promote`) does the counting.
68
+
69
+ **Three open entries under one signature** graduate the lesson into
70
+ `.tyran/knowledge/`, where every handoff touching those paths already delivers
71
+ it. **Five, still recurring after the knowledge entry shipped**, is evidence
72
+ the delivered rule was not enough — the strongest argument for law there is —
73
+ and at five `mistakes.mjs promote --law` **writes the rule into your
74
+ `CLAUDE.md`**. Not a proposal, not a queue: an autonomous write, between
75
+ `<!-- tyran:rules start -->` and `<!-- tyran:rules end -->` and never a byte
76
+ outside those markers. The line names the rule, its signature and the dated
77
+ entries that earned it; a `decision` event records the act; `--dry-run` prints
78
+ the line and writes nothing. You say no by deleting the line — the entries are
79
+ already at status `law`, so nothing puts it back. A fence that is absent is
80
+ appended once at the end, with its heading, and existing prose is never
81
+ reflowed; a fence that is malformed is refused by name, with nothing written.
82
+
83
+ The safety story is a boundary rather than a sentence. The shipped policy now
84
+ classes `CLAUDE.md` as **GATED**, which bans the hand and not the mechanism: a
85
+ subagent's free-hand `Write` is denied, while the script that demands five
86
+ recorded occurrences passes. Until this rule, the gate was silent on repo-root
87
+ files — its governed namespace is `.tyran/`, `.claude/` and the enforcement
88
+ scripts — so a subagent could rewrite the law it was bound by and nothing had
89
+ an opinion. An explicit rule outranks that namespace test, which is why one
90
+ line is enough. Seeding has always been create-only, so existing installs keep
91
+ their own policy untouched.
92
+
93
+ Seeding `MISTAKES.md` is create-only too, and **deleting the file is the whole
94
+ opt-out** — no knob for a file you can remove. `doctor --state` grew three
95
+ codes, 54 → **57**: `mistakes-repeat-unpromoted` (info — a lesson has earned
96
+ promotion), `mistakes-unreadable` (warning), and `claude-md-fence-missing`
97
+ (info — entries claim `law` but no fence exists to hold the rule). An absent
98
+ ledger is never a finding.
99
+
100
+ Stated rather than discovered: `MISTAKES.md` is **authored, not a byte-checked
101
+ projection**. A projection would report a hand edit as drift and destroy it on
102
+ the next render, and a human correcting a wrong root cause is the most valuable
103
+ edit this file will ever get. The cost is that nothing compares it to the
104
+ journal, so it can drift. Every entry cites its initiative and the event id
105
+ that proves it, which makes drift auditable by a human and **not** enforced by
106
+ a gate — a weaker guarantee than the projections carry, and both docs surfaces
107
+ say so instead of leaving you to assume parity.
108
+
109
+ This repository ships its own `MISTAKES.md`, five entries, one of them earned
110
+ during this release: the control-character write-guard refused an edit twice
111
+ because the editing tool turns `\uXXXX` escape text into the character itself,
112
+ so a regex class typed as escapes reached disk as raw C0 and bidi codepoints.
113
+ The guard was working; the author was the attacker.
114
+
115
+ ### Keep the machine awake while the watcher waits
116
+
117
+ The overnight resume watcher's whole job is to be asleep for hours, which is
118
+ exactly the interval a laptop chooses to suspend in — and a suspended machine
119
+ takes the watcher and the network with it. `limits.keep_awake` (a real boolean,
120
+ default `false`) wraps the wait in a system-sleep inhibitor: `caffeinate -is`
121
+ on macOS, `systemd-inhibit --what=idle:sleep` on Linux. **Never `caffeinate
122
+ -d`**: that blocks the display sleep and with it the screen lock, and a machine
123
+ left running overnight that never locks is a security regression. The inhibitor
124
+ is released on every exit path including `SIGINT` and `SIGTERM`, an unsupported
125
+ platform degrades to a no-op instead of refusing to wait, and
126
+ `overnight.mjs schedule` tells you which way the knob is set — as a warning,
127
+ never a refusal.
128
+
129
+ ### Measured
130
+
131
+ `node --test "tests/**/*.test.mjs"`: **1133 unit tests, 0 failures** — 34 of
132
+ them new in `tests/unit/mistakes.test.mjs` (the entry format, the counting
133
+ thresholds, the fence, and every refusal), 11 in `keepawake.test.mjs`.
134
+ `scan-control-chars`: clean over 185 tracked text files. The skill description
135
+ budget is unchanged at **4352 / 5000** — this release adds no skill and no
136
+ agent.
137
+
3
138
  ## 0.1.13 — 2026-08-13
4
139
 
5
140
  ### 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
 
@@ -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.** Stop only for product or visual
52
- decisions, or when something would cross a boundary the handoff named —
53
- then stop and ask the conductor. "Shall I continue?" is forbidden.
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
- step 3 — one home, not two), and retire or split entries
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
@@ -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.',
@@ -17,13 +17,14 @@
17
17
  * worse bug than the missing summary.
18
18
  */
19
19
  import { execFileSync } from 'node:child_process';
20
- import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
20
+ import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
21
21
  import { cpus, totalmem } from 'node:os';
22
22
  import { dirname, isAbsolute, join, resolve } from 'node:path';
23
23
  import { fileURLToPath } from 'node:url';
24
24
 
25
25
  import { checkHooks } from '../../scripts/hooks-check.mjs';
26
26
  import { readJournal } from '../../scripts/journal.mjs';
27
+ import { SESSION_ID_RE } from '../../scripts/overnight.mjs';
27
28
  import { fold, inlinePlain, progressLine } from '../../scripts/project.mjs';
28
29
  import { field, main, runProbe } from './hook-io.mjs';
29
30
 
@@ -206,7 +207,19 @@ export function renderContext({ repoRoot, initiatives, doctor, hardware, nowIso,
206
207
  const openGates = state.openGates ?? [];
207
208
  if (openGates.length > 0) {
208
209
  lines.push(`- Open gates (${openGates.length}):`);
209
- lines.push(...rows(openGates, (g) => ` - ${inlinePlain(g.kind)}: ${inlinePlain(g.result ?? 'open')} (${inlinePlain(g.ts)})`));
210
+ // The QUESTION, not only the gate's name: an ask is a gate whose kind is
211
+ // its id, and `Q-7: WAITING_ON_OPERATOR` tells a resumed conductor that
212
+ // it is waiting without telling it what it asked — which is a
213
+ // re-litigation after every compaction.
214
+ lines.push(
215
+ ...rows(
216
+ openGates,
217
+ (g) =>
218
+ ` - ${inlinePlain(g.kind)}: ${inlinePlain(g.result ?? 'open')}` +
219
+ (g.question ? ` — ${inlinePlain(g.question)}` : '') +
220
+ ` (${inlinePlain(g.ts)})`,
221
+ ),
222
+ );
210
223
  }
211
224
 
212
225
  const leases = [...(state.leases?.values() ?? [])];
@@ -335,6 +348,59 @@ export function renderPauseNotice(marker, nowIso) {
335
348
  );
336
349
  }
337
350
 
351
+ /** Where the resumable session id is recorded, relative to `.tyran`. */
352
+ export const CONDUCTOR_RELPATH = join('state', 'conductor.json');
353
+
354
+ /**
355
+ * Record this session so `answer.mjs apply --resume` can put the swarm back on
356
+ * it. Until this existed a resumable session id was written ONLY by a
357
+ * usage-limit pause or by the operator-installed statusline, so a repo with
358
+ * neither had no way to be resumed at all.
359
+ *
360
+ * THE CONTRACT, because a reader will otherwise infer more than this process
361
+ * can vouch for. The file carries exactly three fields:
362
+ *
363
+ * - `session_id` — shape-checked against SESSION_ID_RE before it is written,
364
+ * because it becomes an argument of a `claude --resume` command and this
365
+ * file is the only thing vouching for it;
366
+ * - `started_at` — the moment of THIS `SessionStart`, which fires on
367
+ * `startup`, `resume` and `compact` (hooks.json's matcher), so it is the
368
+ * last time the session announced itself, not the time it began;
369
+ * - `cwd` — the repo root this probe resolved.
370
+ *
371
+ * There is deliberately NO liveness signal, and no pid. The only pid a hook
372
+ * can observe is its OWN: this process is spawned per event and exits within
373
+ * a second, so a recorded pid is dead before anyone reads it and, once the OS
374
+ * recycles the number, names a stranger. A consumer treating it as "the
375
+ * conductor is alive" is wrong in both directions — never true while the
376
+ * session runs, sometimes true after it is gone. Nothing else in a
377
+ * `SessionStart` payload has been MEASURED to track the session's lifetime
378
+ * (see hooks/HOOK-CONTRACT-MEASURED.md), so this file says only that the
379
+ * session id existed at `started_at`, and a consumer may conclude only that.
380
+ *
381
+ * Best-effort, and inside its own try/catch: `SessionStart` has no way to
382
+ * refuse anything (ADR-22), so a probe that threw here would cost the user
383
+ * their session to report that a convenience file could not be written.
384
+ * `.tyran/state/**` is the AUTO policy class already, so no policy moves.
385
+ */
386
+ export function recordConductor(stateDir, input, { now = new Date(), cwd = null } = {}) {
387
+ try {
388
+ const sessionId = field(input, 'session_id');
389
+ if (typeof sessionId !== 'string' || !SESSION_ID_RE.test(sessionId)) return false;
390
+ const target = join(stateDir, CONDUCTOR_RELPATH);
391
+ mkdirSync(dirname(target), { recursive: true });
392
+ const doc = { session_id: sessionId, started_at: now.toISOString(), cwd: cwd ?? dirname(stateDir) };
393
+ // The pid names the TEMP file only — two hook processes writing at once
394
+ // must not collide on one name. It is never part of the record.
395
+ const temp = join(dirname(target), `.conductor-${process.pid}.tmp`);
396
+ writeFileSync(temp, JSON.stringify(doc, null, 2) + '\n');
397
+ renameSync(temp, target);
398
+ return true;
399
+ } catch {
400
+ return false; // a probe never fails a session over a courtesy file
401
+ }
402
+ }
403
+
338
404
  /** The pause marker, if one is active. Garbage reads as absent. */
339
405
  export function readPauseMarker(stateDir) {
340
406
  try {
@@ -357,6 +423,7 @@ export async function buildContext({ input, now = new Date(), env = process.env,
357
423
  if (repoRoot === null) return fitBudget(warning);
358
424
  const stateDir = join(repoRoot, '.tyran');
359
425
  if (!existsSync(stateDir)) return fitBudget(warning); // not a Tyran repo — but a dead gate still counts
426
+ recordConductor(stateDir, input, { now, cwd: repoRoot });
360
427
  const nowIso = now.toISOString();
361
428
  return fitBudget(
362
429
  warning +
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.13",
3
+ "version": "0.1.15",
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": {