@jjanczur/tyran 0.1.14 → 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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +47 -0
- package/README.md +2 -1
- package/agents/implementer.md +15 -3
- package/agents/reviewer.md +7 -0
- package/bin/tyran.mjs +4 -0
- 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 +61 -0
- package/scripts/journal.mjs +79 -1
- package/scripts/overnight.mjs +4 -2
- package/scripts/project.mjs +15 -3
- package/scripts/scan-repo.mjs +6 -0
- package/scripts/tiers.mjs +17 -0
- package/skills/run/SKILL.md +27 -6
|
@@ -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.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.
|
|
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,52 @@
|
|
|
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
|
+
|
|
3
50
|
## 0.1.14 — 2026-08-14
|
|
4
51
|
|
|
5
52
|
### The repository remembers what went wrong — and eventually writes it into law
|
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
|
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/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
|
@@ -88,6 +88,10 @@ export const COMMANDS = {
|
|
|
88
88
|
'board.mjs',
|
|
89
89
|
'Render the cross-initiative kanban board — BOARD.md, board.json and the board.html dashboard — from the journals under .tyran/state/.',
|
|
90
90
|
],
|
|
91
|
+
answer: [
|
|
92
|
+
'answer.mjs',
|
|
93
|
+
'Write the sheet of questions waiting on you, then fold your answers back into the journal.',
|
|
94
|
+
],
|
|
91
95
|
'stop-check': [
|
|
92
96
|
'stop-check.mjs',
|
|
93
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
|
-
|
|
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.
|
|
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": {
|